akari-video 0.1.13 → 0.1.15

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.15",
   "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,8 @@
     "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-captions-emphasis-words-v0.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-17-data-contract-versioning.md

@@ -97,3 +97,11 @@ edit.json の `version` は変わらないし、edit.json が `version: 1` に
 task `2026-08-20-v2-audio-tracks` に限り、「機能追加禁止・バグ修正のみ」の明示承認済み・1 回限りの例外として、v0/v1 の `audio.sfx[]`・`audio.narration[]`・`audio.bgm` を v2 の audio lane `tracks[].items[]` へ移す変換を追加した。出力側の `at` / `duration` は整数フレームへ確定し、素材側の `in` / `out` と fade / `bgm.in` は秒のまま保持する。実尺が旧形式だけでは決まらない音声は `duration: 0` センチネルとし、この変換器では ffprobe しない。トップレベル `audio` は `master` が宣言されている場合だけ残す。
 
 これは凍結前に許可された最後の機能追加である。今後この変換器へさらに変換能力を足さず、§6 の期限どおり本体から分離・削除する。
+
+### 6.2 filter レイヤー転写と emphasis_words 移送（2026-08-23・1 回限りの例外）
+
+task `2026-08-23-migrate-filter-emphasis-exception` に限り、2026-08-23 オーナー裁定による「機能追加禁止・バグ修正のみ」の明示承認済み・1 回限りの例外として、v0/v1 の独立した `kind: "filter"` レイヤーを v2 の filter source へ転写し、トップレベル `emphasis_words[]` を edit.json v2 から除外して object ルートの `captions.json.emphasis_words[]` へ移送する変換を追加した。media 系レイヤー（`video` / `baked`）に直付けされた `filter` は v2 に等価表現が無いため転写対象外とし、理由付きで変換を停止する。移送時は edit.json と captions.json の原文をそれぞれ退避し、1 手の revert で両方を復元する。移送先が無い、配列ルートである、または既に `emphasis_words` を持つ場合は理由付きで停止する。
+
+2026-08-21 の廃止裁定は fieldtest 60 本を母集団とし、本番リールでの使用が調査圏外だったという母集団瑕疵があったため、本例外で既存データを損失なく移す。
+
+これ以後この変換器へさらに変換能力を足さず、§6 の期限どおり本体から分離・削除する。

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-captions-emphasis-words-v0.md

@@ -0,0 +1,76 @@
+# captions.json v0 語レベル演出（emphasis_words）データ契約
+
+- 日付: 2026-08-23
+- 状態: 実装ラウンドの SSOT（`captions.json` の席と優先順を確定）
+- 前提: [edit.json v1 語レベル演出契約](contract-2026-07-23-edit-json-v1-emphasis-words.md)
+- スコープ: `captions.json` の object ルートに置くトップレベル任意フィールド
+  `emphasis_words[]` と、旧 `edit.json` 席との読取優先順
+
+## 背景
+
+字幕表示に属する語レベル演出は、編集タイムラインではなく字幕の SSOT である `captions.json` 側へ置く。
+`edit.json` v2 から `emphasis_words` を廃止した 2026-08-21 裁定は維持し、v2 の exact-keys に席を
+戻さない。一方、その裁定の根拠だった fieldtest 60 本の使用 0 件は母集団外の本番リールを含んでおらず、
+本番リールでは 15 語が実際に使用されていたため、「語レベル演出自体が不要」という根拠は訂正する。
+
+## 1. 席
+
+`captions.json` が object ルートのときだけ、トップレベルに `emphasis_words[]` を任意で置ける。
+
+```jsonc
+{
+  "emphasis_words": [
+    {
+      "id": "e-0001",
+      "src": "main",
+      "t_start": 12.08,
+      "t_end": 12.44,
+      "word": "最高",
+      "emotion": "joy",
+      "style_hint": "size-pulse"
+    }
+  ],
+  "captions": [ /* 既存のまま */ ]
+}
+```
+
+従来の配列ルート（`[{ ...caption... }]`）にはトップレベルのフィールドを置けないため、
+`emphasis_words[]` の席はない。語レベル演出を書く場合は object ルートへ移し、既存配列を
+`captions[]` に包む。
+
+## 2. レコード契約と差分
+
+レコード形、フィールド語彙、source 秒アンカー、実測 word-level タイムスタンプを写す規律、
+選定規律、劣化規約はすべて
+[edit.json v1 語レベル演出契約](contract-2026-07-23-edit-json-v1-emphasis-words.md) と同じである。
+本契約が定める差分は次の 2 点だけである。
+
+1. 配列の置き場を `edit.json.emphasis_words` から、object ルートの
+   `captions.json.emphasis_words` へ移す。
+2. `edit.json` v2 へは書かない。v0/v1 の旧席は後方互換の読取専用として残す。
+
+したがって各レコードは `{ id, word, emotion, src?, t_start, t_end, style_hint? }` で、`id` は
+`^e-\d{4}$` かつファイル内一意、`word` と `emotion` は空でない文字列、時刻は source 秒で
+`0 <= t_start < t_end` とする。`emotion` は `joy` / `pain` / `surprise` / `anger` / `sadness` /
+`emphasis` を標準語彙として使うが、v1 契約どおり enum 強制はしない。`style_hint` も描画側への
+提案に留まる。
+
+## 3. 読取優先順
+
+消費側は次の優先順で 1 つの席だけを読む。
+
+1. object ルートの `captions.json` に `emphasis_words` キーが在れば、その値を採用する。
+2. キーが無ければ、v0/v1 の `edit.json.emphasis_words` を後方互換として読む。
+3. どちらにも無ければ語レベル演出なしとする。
+
+両方の席が在る場合もマージしない。`captions.json` 側だけを採用し、警告は出さない。これにより
+新しい字幕 SSOT が常に優先される一方、`captions.json` に席を持たない既存 v0/v1 プロジェクトは
+従来どおり `edit.json` 側だけで描画され、回帰しない。
+
+## 4. 検証責務
+
+`captions.schema.json` は object ルートだけに任意の `emphasis_words[]` を定義し、要素の必須項目、
+型、`id` 形式、非負時刻、非空の `word` / `emotion` を検査する。JSON Schema 標準では兄弟値を
+比較できない `t_end > t_start` と、配列内の `id` 一意性は `validate-captions.mjs` が検査する。
+語と `captions[].words[]` の実測値の突き合わせは v1 契約と同じく書き手の規律であり、静的検証では
+行わない。

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.15",
   "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."
   }