akari-video 0.1.68 → 0.1.70

package/package.json

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

@@ -2,7 +2,7 @@ import { existsSync } from 'node:fs';
 import { spawnSync } from 'node:child_process';
 import path from 'node:path';
 
-import { resolveLauncherAssets } from './repo-assets.mjs';
+import { FINGER_FRAME_SCRIPT_RELATIVE, resolveLauncherAssets } from './repo-assets.mjs';
 
 const commands = [
   'beat-sync-beatmap',
@@ -31,12 +31,10 @@ export async function runInternalCommand(args, options = {}) {
     return { exitCode: 0 };
   }
 
-  // vision-finger-frame は task/2026-08-11-finger-frame-generator の境界規約により
-  // repo-assets.mjs（別タスク task/2026-08-11-eye-bar-generator と衝突しやすい共有ファイル）を
-  // 編集せず、他コマンドと違い assets.repoRoot から自己解決する（resolveRepoAssets() 側に
-  // フィールドを追加していない唯一の例外 -- 経緯は非公開の内部記録を参照）。
+  // vision-finger-frame は他コマンドと違い assets.repoRoot から自己解決するが、
+  // 相対パス自体は配布検査と共有する repo-assets.mjs の正本を使う。
   const fingerFrameScript = assets.repoRoot
-    ? path.join(assets.repoRoot, 'packages', 'akari-tools', 'bin', 'finger-frame.mjs')
+    ? path.join(assets.repoRoot, FINGER_FRAME_SCRIPT_RELATIVE)
     : null;
 
   const definitions = {

package/src/repo-assets.mjs

@@ -19,28 +19,59 @@ const SKILLS_MARKER = path.join('skills', 'analyze-footage', 'SKILL.md');
 // 雛形側の .gitignore 実体は project-scaffold の writeFallbackTemplate が補完する。
 const TEMPLATE_MARKER = path.join('templates', 'project-default', 'CLAUDE.md');
 const SCHEMAS_MARKER = path.join('packages', 'schemas', 'analysis.schema.json');
-const DOCTOR_SCRIPT_RELATIVE = path.join('skills', 'manage-connections', 'bin', 'doctor.mjs');
-const SCAFFOLD_MODULE_RELATIVE = path.join('packages', 'project-scaffold', 'src', 'index.mjs');
+export const DOCTOR_SCRIPT_RELATIVE = path.join('skills', 'manage-connections', 'bin', 'doctor.mjs');
+export const SCAFFOLD_MODULE_RELATIVE = path.join('packages', 'project-scaffold', 'src', 'index.mjs');
 // 作業場（creator-root）モジュール。① Wave（packages/creator-root）の成果物で、本パッケージ
 // からは読み取り専用（動的 import のみ）。scaffoldModulePath と同型の解決方式。
-const CREATOR_ROOT_MODULE_RELATIVE = path.join('packages', 'creator-root', 'src', 'index.mjs');
+export const CREATOR_ROOT_MODULE_RELATIVE = path.join('packages', 'creator-root', 'src', 'index.mjs');
 // 公式音源ライブラリ（AKARI Sounds）の一括取得スクリプト。初回動線（sounds-setup.mjs）と
 // `akari sounds` が子プロセスとして起動する。未同梱なら null（機能スキップ）。
-const AUDIO_FETCH_SCRIPT_RELATIVE = path.join('packages', 'audio-library-setup', 'bin', 'fetch-akari-sounds.mjs');
+export const AUDIO_FETCH_SCRIPT_RELATIVE = path.join('packages', 'audio-library-setup', 'bin', 'fetch-akari-sounds.mjs');
 // 素材 resolver（アカウントの素材 = 無料 + 購入済みの一覧・取得）の CLI 実体。
 // `akari assets <list|fetch|sync|...>`（assets-command.mjs）が子プロセスとして起動する。
 // 未同梱なら null（`akari assets` はその旨のエラーを返す。他コマンドは無影響）。
-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 DECISION_LOG_SCRIPT_RELATIVE = path.join('packages', 'akari-tools', 'bin', 'decision-log.mjs');
-const CAPTIONS_SCRIPT_RELATIVE = path.join('packages', 'akari-tools', 'bin', 'captions.mjs');
+export const ASSET_RESOLVER_CLI_RELATIVE = path.join('packages', 'asset-resolver', 'bin', 'akari-assets.mjs');
+export const BEATMAP_SCRIPT_RELATIVE = path.join('packages', 'akari-tools', 'bin', 'beatmap.mjs');
+export const PROBE_FRAME_SCRIPT_RELATIVE = path.join('packages', 'akari-tools', 'bin', 'probe-frame.mjs');
+export const DECISION_LOG_SCRIPT_RELATIVE = path.join('packages', 'akari-tools', 'bin', 'decision-log.mjs');
+export const CAPTIONS_SCRIPT_RELATIVE = path.join('packages', 'akari-tools', 'bin', 'captions.mjs');
 // capture-command.mjs のエラー文と apps/shell の同梱テストが同じ相対パスを名指しできるよう export する。
 export 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');
+export const RENDER_WHEN_IDLE_SCRIPT_RELATIVE = path.join('packages', 'akari-tools', 'bin', 'render-when-idle.sh');
+export const EYE_BAR_SCRIPT_RELATIVE = path.join('packages', 'akari-tools', 'bin', 'eye-bar.mjs');
+export const FINGER_FRAME_SCRIPT_RELATIVE = path.join('packages', 'akari-tools', 'bin', 'finger-frame.mjs');
+export const MEDIA_SCRIPT_RELATIVE = path.join('packages', 'akari-tools', 'bin', 'media.mjs');
+export const WORD_BOOK_SCRIPT_RELATIVE = path.join('packages', 'akari-tools', 'bin', 'word-book.mjs');
 export const GENERATE_CLI_RELATIVE = path.join('packages', 'generate', 'src', 'cli', 'index.mjs');
 export const STORYBOARD_CLI_RELATIVE = path.join('packages', 'decision-cards', 'render-storyboard-print.mjs');
+export const WORLD_CLI_RELATIVE = path.join('packages', 'akari-tools', 'bin', 'world.mjs');
+export const WORLD_VALIDATOR_RELATIVE = path.join('packages', 'schemas', 'bin', 'validate-world-map.mjs');
+
+// launcher が直接または起動した CLI の子プロセスとして解決する実行体の正本。
+// launcher-assets は resolveLauncherAssets() が資産フィールド単位で vendor を補完できる経路、
+// resources は assets.repoRoot または実行中 CLI の位置から自己解決し、vendor を見ない経路。
+// relative は上の解決定数だけから組み立て、配布検査と実行時解決の文字列を乖離させない。
+export const LAUNCHER_SUBCOMMAND_EXECUTABLES = [
+  { command: '接続 doctor（manage-connections）', relative: DOCTOR_SCRIPT_RELATIVE, resolution: 'launcher-assets' },
+  { command: 'akari new', relative: SCAFFOLD_MODULE_RELATIVE, resolution: 'launcher-assets' },
+  { command: '初回動線（first-run）の作業場モジュール', relative: CREATOR_ROOT_MODULE_RELATIVE, resolution: 'launcher-assets' },
+  { command: 'akari sounds', relative: AUDIO_FETCH_SCRIPT_RELATIVE, resolution: 'launcher-assets' },
+  { command: 'akari assets', relative: ASSET_RESOLVER_CLI_RELATIVE, resolution: 'launcher-assets' },
+  { command: 'akari internal beat-sync-beatmap', relative: BEATMAP_SCRIPT_RELATIVE, resolution: 'launcher-assets' },
+  { command: 'akari internal beat-sync-probe-frame', relative: PROBE_FRAME_SCRIPT_RELATIVE, resolution: 'launcher-assets' },
+  { command: 'akari decision-log', relative: DECISION_LOG_SCRIPT_RELATIVE, resolution: 'launcher-assets' },
+  { command: 'akari captions', relative: CAPTIONS_SCRIPT_RELATIVE, resolution: 'launcher-assets' },
+  { command: 'akari capture', relative: CAPTURE_SCRIPT_RELATIVE, resolution: 'launcher-assets' },
+  { command: 'akari internal beat-sync-render-when-idle', relative: RENDER_WHEN_IDLE_SCRIPT_RELATIVE, resolution: 'launcher-assets' },
+  { command: 'akari internal eye-bar', relative: EYE_BAR_SCRIPT_RELATIVE, resolution: 'launcher-assets' },
+  { command: 'akari internal vision-finger-frame', relative: FINGER_FRAME_SCRIPT_RELATIVE, resolution: 'resources' },
+  { command: 'akari media', relative: MEDIA_SCRIPT_RELATIVE, resolution: 'launcher-assets' },
+  { command: 'akari word-book', relative: WORD_BOOK_SCRIPT_RELATIVE, resolution: 'launcher-assets' },
+  { command: 'akari generate', relative: GENERATE_CLI_RELATIVE, resolution: 'launcher-assets' },
+  { command: 'akari storyboard', relative: STORYBOARD_CLI_RELATIVE, resolution: 'launcher-assets' },
+  { command: 'akari world', relative: WORLD_CLI_RELATIVE, resolution: 'resources' },
+  { command: 'akari world check', relative: WORLD_VALIDATOR_RELATIVE, resolution: 'resources' }
+];
 
 /**
  * 指定ルート配下に同梱されているスキル正本・雛形・schemas・scaffold 実装・creator-root
@@ -59,9 +90,9 @@ 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');
+  const mediaScript = path.join(repoRoot, MEDIA_SCRIPT_RELATIVE);
   const decisionLogScript = path.join(repoRoot, DECISION_LOG_SCRIPT_RELATIVE);
-  const wordBookScript = path.join(repoRoot, 'packages', 'akari-tools', 'bin', 'word-book.mjs');
+  const wordBookScript = path.join(repoRoot, WORD_BOOK_SCRIPT_RELATIVE);
   const generateScript = path.join(repoRoot, GENERATE_CLI_RELATIVE);
   const storyboardScript = path.join(repoRoot, STORYBOARD_CLI_RELATIVE);
 

package/src/vendor-sources.mjs

@@ -0,0 +1,47 @@
+// prepack の vendor コピー、配布同梱ゲート、GPL 再配布ゲートが、vendor/ へ入る
+// リポジトリ相対パスを同じ prefix 規則で判定するための共有正本。prepack.mjs は
+// import 時にコピーを始める副作用モジュールなので、安全に共有できるデータだけを分離した。
+// GPL 再配布ゲートは import せずテキストとして配列リテラルを読む。この宣言を
+// `export const` + `VENDOR_SOURCES = [` の形とベタ書き文字列のまま保つこと。変数展開・spread・
+// 他ファイルからの合成を入れると、安全に検査できないためゲートが fail-closed で落ちる。
+export const VENDOR_SOURCES = [
+  'skills',
+  'templates/project-default',
+  'presets/luts',
+  // edit-lint は外部 npm 依存ゼロだが、src から edit-store のビルド済み実装と
+  // textanim preset を参照する。既に同梱済みの schemas / audio-library-setup /
+  // media-bin と合わせ、CLI の実行時閉包を明示的に揃える。
+  'presets/textanim',
+  'assets/font/noto-sans-jp/NotoSansJP-Variable.ttf',
+  'packages/schemas',
+  'packages/project-scaffold',
+  // analysis-report は package.json / README.md を capability source として既に収集する。
+  // 実行に必要な CLI と同居必須テンプレートだけを追加し、test/ は配布しない。
+  'packages/analysis-report/render-analysis-report.mjs',
+  'packages/analysis-report/template.html',
+  // decision-log-report も package.json / README.md は capability source として収集する。
+  // 実行に必要な CLI と同居必須テンプレートだけを追加し、test/ は配布しない。
+  'packages/decision-log-report/render-decision-log-report.mjs',
+  'packages/decision-log-report/template.html',
+  'packages/edit-lint/bin',
+  'packages/edit-lint/src',
+  'packages/edit-store/lib',
+  // 作業場（creator-root）モジュール。npm 配布時も初回動線（first-run.mjs 経由の
+  // 動的 import）が機能するよう同梱する。未同梱の場合は repo-assets.mjs 側で
+  // creatorRootModulePath が null になり、現行動作へフォールバックする。
+  'packages/creator-root',
+  // 公式音源ライブラリ（AKARI Sounds）の一括取得（sounds-setup.mjs / `akari sounds`）。
+  // media-bin は fetch スクリプトの preview.png 生成（waveform-preview.mjs）が ffmpeg 解決に
+  // 使う。未同梱なら audioFetchScriptPath が null になり、音源セットアップだけスキップされる。
+  'packages/audio-library-setup',
+  'packages/media-bin',
+  // 素材 resolver（`akari assets` — アカウントの素材 = 無料 + 購入済みの一覧・取得）。
+  // 未同梱なら assetResolverCliPath が null になり、`akari assets` だけスキップされる
+  // （タスク契約 2026-08-09-agent-assets-discovery）。
+  'packages/asset-resolver',
+  // 履歴に何を入れるかの宣言（history-policy.mjs）。project-scaffold が相対パスで参照するため、
+  // vendor ミラーにもモノレポと同じ深さで置く（`vendor/packages/akari-launcher/src/` →
+  // `vendor/packages/project-scaffold/src/` から `../../akari-launcher/src/` で解決できる）。
+  // 本体の src/ にも同じファイルが入るが、配布物の中で相対パスを 1 本に保つ方を採る。
+  'packages/akari-launcher/src/history-policy.mjs'
+];

package/src/world-command.mjs

@@ -2,12 +2,12 @@ import { existsSync } from 'node:fs';
 import { spawnSync } from 'node:child_process';
 import path from 'node:path';
 
-import { resolveLauncherAssets } from './repo-assets.mjs';
+import { resolveLauncherAssets, WORLD_CLI_RELATIVE } from './repo-assets.mjs';
 
 export async function runWorldCommand(args, options = {}) {
   const logError = options.logError ?? ((line) => console.error(line));
   const assets = options.assets ?? resolveLauncherAssets();
-  const script = assets.repoRoot ? path.join(assets.repoRoot, 'packages', 'akari-tools', 'bin', 'world.mjs') : null;
+  const script = assets.repoRoot ? path.join(assets.repoRoot, WORLD_CLI_RELATIVE) : null;
   if (!script || !existsSync(script)) {
     logError('内部コマンド world の実行スクリプトが見つかりません。AKARI Video の完全な checkout または配布物を確認してください。');
     return { exitCode: 1 };

package/vendor/docs/contract-2026-09-13-extension-kit-v0.md

@@ -70,6 +70,10 @@ claude plugin install akari-kits@akari-kits
 
 Codex、Cursor、opencode では、プロジェクトの `.agents/.codex/.cursor/.opencode/skills` へキットスキルも合成する。同名があれば純正スキルを優先する。plugin が利用できない環境でも `~/.akari/kits/plugin/skills/<name>/SKILL.md` を直接読める。
 
+## 5. アプリ（ホームの拡張キットカード）
+
+ホームの AKARI Store カードの隣に拡張キットカードを 1 枚出し、未接続では出さず、導入済みは id・version・スキル名・素材数の一覧と未有効化時の有効化案内、購入済み・未導入は `akari store install <id>` の案内、未購入は教材の引換ページの案内、という 3 状態とする（アプリはコマンドを実行せず、コピーと外部ブラウザ起動だけを行う）。
+
 ## 6. 更新と版
 
 キットの版は Store の整数版とする。`akari store status` が導入済みの id、version、スキル名、素材数を表示し、同じ `akari store install` で新版へ置換する。

package/vendor/docs/contract-2026-09-13-world-map-v0.md

@@ -39,6 +39,10 @@ spatial world は three 断片で構成し、座標・床・背景・霧を宣
 
 ## 5. 地図 UI
 
+- 実装のマーカー判定は `akari-shell-strip` の ContextKey `akari.worldMap` に一元化する。
+- main の「地図」タブは `akari-world-view` が担う。
+- タイムラインのワールド帯と地図インスペクターは `akari-annotations` が担う。
+
 地図 UI は world-map を読み取り専用で表示する。2D 俯瞰、ワールド帯、再生時刻に追従する撮影枠、選択中の stop / edge 詳細を提供し、データの編集機能は持たない。
 
 ## 6. 制作フロー

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

@@ -1,6 +1,6 @@
 {
   "name": "akari-video",
-  "version": "0.1.68",
+  "version": "0.1.70",
   "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. Use `akari doctor --json` and run the path reported in `render_cut.path`. Full installations provide it in a monorepo checkout, ~/.akari/app, /Applications/AKARI Video.app/Contents/Resources/packages, or %LOCALAPPDATA%\\Programs\\@akari-videoshell\\resources\\packages.]",
   "type": "module",
   "files": [

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

@@ -2,10 +2,37 @@
 // 「このアカウントで使える素材 = 無料全部 + 購入済み」の 1 ビュー（設計契約 §8）の核。
 
 import { loadCatalog } from './catalog.mjs';
-import { resolveAkariHome, resolveEffectiveBase } from './env.mjs';
+import { resolveAkariHome, resolveEffectiveBase, resolveEntitlementsUrl } from './env.mjs';
 import { fetchEntitlements, readStoreCredentials } from './entitlements.mjs';
 import { scanLocalLibrary } from './library.mjs';
 
+async function fetchEntitledProducts({ env, fetchImpl }) {
+  const credentials = await readStoreCredentials(env);
+  if (!credentials) return [];
+  try {
+    const response = await fetchImpl(resolveEntitlementsUrl(env, credentials), {
+      headers: { authorization: `Bearer ${credentials.token}` },
+    });
+    if (!response.ok) return [];
+    const data = await response.json();
+    if (!Array.isArray(data?.entitlements)) return [];
+    return data.entitlements.flatMap((entry) => {
+      if (typeof entry === 'string') {
+        return entry ? [{ id: entry, kind: null, currentVersion: null }] : [];
+      }
+      const id = entry?.product_id ?? entry?.id;
+      if (typeof id !== 'string' || !id) return [];
+      return [{
+        id,
+        kind: typeof entry.kind === 'string' ? entry.kind : null,
+        currentVersion: Number.isFinite(entry.current_version) ? entry.current_version : null,
+      }];
+    });
+  } catch {
+    return [];
+  }
+}
+
 /**
  * @returns {Promise<{ home: string, base: string, catalogVersion: string|null, entitlementsStatus: 'ok'|'no_credentials'|'unauthorized'|'error', items: Array }>}
  * items の各要素はカタログ項目に `state`（'cached' | 'available' | 'locked'）を足したもの。
@@ -22,6 +49,9 @@ export async function composeState({ env = process.env, fetchImpl = fetch } = {}
   const entitlementsResult = hasPaidItems
     ? await fetchEntitlements({ env, fetchImpl })
     : { ids: new Set(), status: await readStoreCredentials(env) ? 'ok' : 'no_credentials' };
+  // entitlements.mjs は id/status だけを返し編集できないため、商品 kind/version は
+  // 同じ API への 2 回目の fail-soft 取得で補う。
+  const entitledProducts = await fetchEntitledProducts({ env, fetchImpl });
 
   const items = catalog.items.map((item) => {
     const key = `${item.category}/${item.id}`;
@@ -38,6 +68,7 @@ export async function composeState({ env = process.env, fetchImpl = fetch } = {}
     base,
     catalogVersion: catalog.version ?? null,
     entitlementsStatus: entitlementsResult.status,
+    entitledProducts,
     items,
   };
 }

package/vendor/packages/asset-resolver/test/catalog-and-state.test.mjs

@@ -50,3 +50,39 @@ test('composeState: ローカルに実体があるものは cached になる', a
   const free = items.find((i) => i.id === 'mini-still');
   assert.equal(free.state, 'cached');
 });
+
+test('composeState: entitledProducts に kit 商品を載せ、資格情報なしでは空配列にする', async () => {
+  const connected = setupFixtureEnv();
+  writeFileSync(
+    path.join(connected.home, 'store-credentials.json'),
+    `${JSON.stringify({ url: 'https://example.invalid/api/store', token: 'akst_test' }, null, 2)}\n`,
+  );
+  let fetchCount = 0;
+  const state = await composeState({
+    env: connected.env,
+    fetchImpl: async () => {
+      fetchCount += 1;
+      return {
+        ok: true,
+        status: 200,
+        json: async () => ({
+          entitlements: [{ product_id: 'world-kit', kind: 'kit', current_version: 3 }],
+        }),
+      };
+    },
+  });
+  assert.deepEqual(state.entitledProducts, [{ id: 'world-kit', kind: 'kit', currentVersion: 3 }]);
+  assert.equal(fetchCount, 2);
+
+  const disconnected = setupFixtureEnv();
+  let disconnectedFetchCount = 0;
+  const disconnectedState = await composeState({
+    env: disconnected.env,
+    fetchImpl: async () => {
+      disconnectedFetchCount += 1;
+      throw new Error('資格情報なしでは呼ばれない');
+    },
+  });
+  assert.deepEqual(disconnectedState.entitledProducts, []);
+  assert.equal(disconnectedFetchCount, 0);
+});

package/vendor/packages/edit-store/lib/generation-meta.d.ts

@@ -11,6 +11,8 @@ export interface GenerationMetaV1 {
     inputs?: {
         first_frame?: {
             sha256?: string;
+            path?: string;
+            source_id?: string | null;
         } | null;
         [key: string]: unknown;
     };
@@ -47,3 +49,14 @@ export declare function bindingShaFor(meta: GenerationMetaV1 | null | undefined)
  * `job.stale_after_s` が未指定・不正な場合は既定 900 秒を使う。
  */
 export declare function resolveGenerationState(meta: GenerationMetaV1 | null | undefined, now: Date | string | number): GenerationState;
+/**
+ * item が現在指している素材へ、生成物側の video サイドカーを逆引きする。
+ * 選択だけを行い、各 surface 固有の orphan / 契約外 status の解決は呼び出し側へ残す。
+ */
+export declare function selectGenerationSidecarForSource<T extends {
+    sourcePath: string;
+    meta?: GenerationMetaV1 | null;
+    binding?: {
+        matches?: boolean;
+    } | null;
+}>(sourcePath: string | undefined, entries: readonly T[], now: Date | string | number): T | undefined;

package/vendor/packages/edit-store/lib/generation-meta.js

@@ -8,6 +8,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.sidecarPathFor = sidecarPathFor;
 exports.bindingShaFor = bindingShaFor;
 exports.resolveGenerationState = resolveGenerationState;
+exports.selectGenerationSidecarForSource = selectGenerationSidecarForSource;
 function sidecarPathFor(sourcePath) {
     return `${sourcePath}.meta.json`;
 }
@@ -15,8 +16,7 @@ function bindingShaFor(meta) {
     if (meta?.status === 'done' && typeof meta.result?.sha256 === 'string') {
         return { sha256: meta.result.sha256, source: 'result' };
     }
-    if ((meta?.kind === 'still' || meta?.status === 'planned')
-        && typeof meta.inputs?.first_frame?.sha256 === 'string') {
+    if (typeof meta?.inputs?.first_frame?.sha256 === 'string') {
         return { sha256: meta.inputs.first_frame.sha256, source: 'first_frame' };
     }
     return null;
@@ -45,3 +45,36 @@ function resolveGenerationState(meta, now) {
     }
     return meta.status;
 }
+/**
+ * item が現在指している素材へ、生成物側の video サイドカーを逆引きする。
+ * 選択だけを行い、各 surface 固有の orphan / 契約外 status の解決は呼び出し側へ残す。
+ */
+function selectGenerationSidecarForSource(sourcePath, entries, now) {
+    if (typeof sourcePath !== 'string')
+        return undefined;
+    const normalizePath = (value) => value.trim().replace(/\\/gu, '/').replace(/^(?:\.\/)+/u, '');
+    const normalizedSourcePath = normalizePath(sourcePath);
+    const direct = entries.find(entry => normalizePath(entry.sourcePath) === normalizedSourcePath);
+    if (direct?.meta?.kind === 'video')
+        return direct;
+    let selected;
+    let selectedStartedAt = Number.NEGATIVE_INFINITY;
+    for (const entry of entries) {
+        const meta = entry.meta;
+        if (meta?.kind !== 'video' || entry.binding?.matches === false)
+            continue;
+        const firstFramePath = meta.inputs?.first_frame?.path;
+        if (typeof firstFramePath !== 'string' || normalizePath(firstFramePath) !== normalizedSourcePath)
+            continue;
+        const state = resolveGenerationState(meta, now);
+        if (state !== 'generating' && state !== 'stale' && state !== 'failed')
+            continue;
+        const startedAt = Date.parse(String(meta.job?.started_at ?? ''));
+        const sortableStartedAt = Number.isFinite(startedAt) ? startedAt : Number.NEGATIVE_INFINITY;
+        if (!selected || sortableStartedAt > selectedStartedAt) {
+            selected = entry;
+            selectedStartedAt = sortableStartedAt;
+        }
+    }
+    return selected ?? direct;
+}