akari-video 0.1.34 → 0.1.36

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "akari-video",
-  "version": "0.1.34",
+  "version": "0.1.36",
   "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

@@ -24,6 +24,7 @@ import {
 import { applySelfUpdate, isRunningFromAppDir, rollbackSelfUpdate } from './self-update.mjs';
 import { runCaptureCommand } from './capture-command.mjs';
 import { runMediaCommand } from './media-command.mjs';
+import { runWordBookCommand } from './word-book-command.mjs';
 import { resolveRuntimePaths } from './runtime-diagnostics.mjs';
 
 /**
@@ -44,6 +45,7 @@ export async function run(args, options = {}) {
   }
   if (args[0] === 'capture') return runCaptureCommand(args.slice(1), options);
   if (args[0] === 'media') return runMediaCommand(args.slice(1), options);
+  if (args[0] === 'word-book') return runWordBookCommand(args.slice(1), options);
 
   const log = options.log ?? ((line) => console.log(line));
   const assets = options.assets ?? resolveLauncherAssets();

package/src/repo-assets.mjs

@@ -55,6 +55,7 @@ export function resolveRepoAssets(repoRoot = DEFAULT_REPO_ROOT_CANDIDATE) {
   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 wordBookScript = path.join(repoRoot, 'packages', 'akari-tools', 'bin', 'word-book.mjs');
 
   return {
     repoRoot,
@@ -71,7 +72,8 @@ export function resolveRepoAssets(repoRoot = DEFAULT_REPO_ROOT_CANDIDATE) {
     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,
-    mediaScript: existsSync(mediaScript) ? mediaScript : null
+    mediaScript: existsSync(mediaScript) ? mediaScript : null,
+    ...(existsSync(wordBookScript) ? { wordBookScript } : {})
   };
 }
 
@@ -105,6 +107,9 @@ export function resolveLauncherAssets({
     ...(candidate.captureScript ?? vendor.captureScript ? { captureScript: candidate.captureScript ?? vendor.captureScript } : {}),
     renderWhenIdleScript: candidate.renderWhenIdleScript ?? vendor.renderWhenIdleScript,
     eyeBarScript: candidate.eyeBarScript ?? vendor.eyeBarScript,
-    mediaScript: candidate.mediaScript ?? vendor.mediaScript
+    mediaScript: candidate.mediaScript ?? vendor.mediaScript,
+    ...(candidate.wordBookScript ?? vendor.wordBookScript
+      ? { wordBookScript: candidate.wordBookScript ?? vendor.wordBookScript }
+      : {})
   };
 }

package/src/word-book-command.mjs

@@ -0,0 +1,16 @@
+import { spawnSync } from "node:child_process";
+
+import { resolveLauncherAssets } from "./repo-assets.mjs";
+
+export async function runWordBookCommand(args, options = {}) {
+  const logError = options.logError ?? ((line) => console.error(line));
+  const assets = options.assets ?? resolveLauncherAssets();
+  const spawn = options.spawn ?? spawnSync;
+  if (!assets.wordBookScript) {
+    logError("akari word-book の実行スクリプトが見つかりません。完全な AKARI Video を再導入してください:");
+    logError("  npm install -g akari-video");
+    return { exitCode: 1 };
+  }
+  const result = spawn(process.execPath, [assets.wordBookScript, ...args], { stdio: "inherit" });
+  return { exitCode: typeof result?.status === "number" ? result.status : 1 };
+}

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

@@ -51,12 +51,14 @@
     "docs/contract-2026-08-29-media-inspect-cli-v0.md",
     "docs/contract-2026-08-30-edit-json-v2-object-tree-v0.md",
     "docs/contract-2026-08-30-motion-and-keyframes-v0.md",
+    "docs/contract-2026-09-02-asset-reference-model.md",
     "docs/contract-2026-09-02-audio-clip-fx-v1.md",
     "docs/contract-2026-09-02-audio-envelope-v1.md",
     "docs/contract-2026-09-02-audio-insert-level-v1.md",
     "docs/contract-2026-09-02-captions-style-preset-v0.md",
     "docs/contract-2026-09-02-export-verify-declared-vs-measured-v0.md",
     "docs/contract-2026-09-02-item-caption-anchor-v0.md",
+    "docs/contract-2026-09-02-shape-item-v0.md",
     "docs/contract-2026-09-02-transcript-unrecognized-spans-v0.md",
     "docs/contract-2026-09-02-word-book-v0.md",
     "packages/akari-launcher/package.json",

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

@@ -73,6 +73,7 @@
 ### 4-1. 画角（`cuts[].framing`）
 
 - **crop と keyframes の併存**: 両方宣言された場合は `keyframes` を優先する。`crop` は「1 点ズームの縮退形」であり、両立させる意味論が無いため（複製 drift の温床にもなる）
+- **幾何の基準（2026-09-02 追記・相互参照）**: `output.geometry` は未指定 = fit 互換 / `"source"` = 実寸基準を表すマーカーで、正本は `docs/contract-2026-08-02-preview-parity.md` §2.2（G1 は描画無変更・framing の再定義は G2）。
 - **scale < 1 の扱い**: `keyframes[].scale` は仕組み上「クロップ窓を縮めて拡大する」ため 1 未満（キャンバスの外まで見せる＝リビール）は原理的に表現できない。レンダ側で `max(1, scale)` にクランプする（silent drop ではなく仕組み上の上限として契約に明記）
 - **crop.w/h が init 一度しか評価されない**: ffmpeg の `crop` フィルタは `x`/`y` は `t` を使った毎フレーム再評価に対応するが、`w`/`h` は（この ffmpeg ビルドで）フィルタ初期化時の一度きりの評価に固定されており `eval` オプション自体が存在しない（実機検証: `t` を含む `w`/`h` 式は `crop=... w='...t...'` で `Error when evaluating the expression` を返す）。そのため実装は「`scale` を `eval=frame` で `width*scale(t) : height*scale(t)` に広げてから固定サイズ `width:height` で `crop` する」方式を採る（クロップ窓の拡大 = `scale` 側の時間関数、パン位置 = `crop` の `x`/`y` の時間関数、という役割分担）
 - **`crop` の `x`/`y` は上流フレームの実サイズを見ない**: 同フィルタの `iw`/`ih` 定数は（動的サイズの上流から来ていても）negotiate 済みの固定リンクサイズを指し、最初のフレームのサイズに固定されたままになることを実機検証で確認した。そのため `crop` の `x`/`y` 式は `iw`/`ih` を参照せず、`scale` 側と同じ `scale(t)` 式をそのまま再計算する（対称的だが唯一 crop から見て正しい現在値）

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

@@ -70,6 +70,13 @@ cut 境界の選択は宣言順ではなく解決済みタイムラインと z-o
   `cut <id>: perspective is not applied by the frame-engine base path yet (issue #39)` を warning に出す（無警告で捨てない）。
 - `freeze = {at_sec, duration_sec}` は指定 frame を保持し、cut の出力尺を `duration_sec` だけ伸ばして
   後続の逐次 cut を移動する。freeze の画と独立音声予定表を混同しない。
+- **`output.geometry`（幾何の基準。2026-09-02 追記）**: 未指定 = **fit 互換**（cut は出力へ contain fit した後に
+  transform。上記の従来どおり）、`"source"` = **実寸基準**（ソース実寸 × scale の box。layer・layer-style cut と同じ幾何）。
+  語彙は `"source"` の 1 つだけで、マーカーが立つのは「今 fit 基準で描かれている全 media item に `scale × fit`
+  （`fit = min(outputW / srcW, outputH / srcH)`・srcW / srcH は表示回転後）を一度だけ焼き込んだ」ことを意味する
+  （部分適用は禁止。移行は `packages/edit-store/bin/normalize-geometry.mjs`）。x / y / rotate は両基準で同じ意味なので触らない。
+  **G1（マーカー・移行・lint の warning `geometry.fit-compat`）ではエンジンはこのマーカーを読まず、描画は 1 バイトも変わらない。
+  描画へ反映するのは G2**。cross ref: `docs/contract-2026-07-22-render-basics.md` §4-1（#6 画角操作）。
 
 **検収:** framing / transform / opacity / freeze を含む base parity **28 点**、freeze をまたぐ
 frame lifetime **1000 コマ**、故意の **1 px** 差分を必ず FAIL させる否定点で判定する。
@@ -277,6 +284,11 @@ lint 実行系が見つからない場合は **fail-open**（2026-08-02 オー
 保存を続行する。書き込みは tmp ファイルへの出力と rename による atomic 更新とする。実装は
 `packages/edit-store` に一本化し、器や入口ごとの独自書き込み実装を追加してはならない。
 
+本編 cut の `crop` 書き戻し（選択枠の辺バー）は **edit.json version 2 の文書だけ**が対象で、legacy の
+`cuts[]` schema には席が無いため読み込み層が拒否する。`output.geometry` を宣言していない文書では、crop の
+無い cut は出力キャンバスへ contain fit されて描かれるので、**初回の crop と同一 patch で `transform.scale`
+へ fit 係数を焼き込む**（ソース実寸基準の layer-style へ移っても画面上の位置・大きさが変わらないため）。
+
 ### 5.4 ペン
 
 ペン描画の単一正本は `packages/pen-visuals` の `PEN_TUNING` と描画プリミティブである。器や overlay

package/vendor/docs/contract-2026-09-02-asset-reference-model.md

@@ -0,0 +1,57 @@
+# contract — 素材の参照モデル v0（共有ライブラリ参照の台帳と解決規則）
+
+- 状態: 実装済み（機械層のみ。シェル UI の採用は後続）
+- 決定日: 2026-09-02
+- 実装: `packages/asset-resolver`（記帳・実体化）/ `packages/render-cut`・`packages/edit-lint`（解決）
+
+## 1. 目的
+
+カタログ素材をプロジェクトごとに実体コピーすると、同じ素材が何度もダウンロード・複製されて
+プロジェクトが肥大する。実体は**マシン単位の共有ライブラリ**（`~/.akari/assets/<category>/<id>/`）に
+1 部だけ置き、プロジェクトには**参照だけを記録**できるようにする。
+
+## 2. 設計の要点
+
+- **edit.json は変えない**。参照素材も従来どおり `assets/<category>/<id>/<file>` の
+  プロジェクト相対パスで宣言される。実体がプロジェクトに無いことは参照台帳が説明する。
+- 参照台帳 = プロジェクトの `.akari/asset-references.json`:
+
+  ```json
+  { "version": 0, "references": [ { "id": "<素材 id>", "category": "<カテゴリ>" } ] }
+  ```
+
+  references は category → id の安定ソート・重複なし。読み手は寛容（無い / 壊れは空扱い）、
+  書き込みは tmp + rename の原子的更新。`version` は台帳自身のスキーマ版数であり
+  edit.json の version とは無関係。
+- **解決規則**: 宣言されたプロジェクト相対パスが `assets/<category>/<id>/<rest>` の形で、
+  (1) プロジェクト実体が存在せず、(2) 台帳に `{category, id}` があるとき、
+  `<AKARI_HOME>/assets/<category>/<id>/<rest>`（AKARI_HOME 既定 `~/.akari`・env で上書き可）へ
+  フォールバックする。解決先は realpath 後も `<AKARI_HOME>/assets` 配下に収まる正規ファイルで
+  あること（`..` 等の脱出は fail-closed で拒否）。
+- render-cut は解決した入力を render inputs 記録に `scope: "library"` として残す
+  （既存 `scope: "akari"` と同列の additive 記録）。edit-lint は解決できる参照を欠落と報告せず、
+  台帳にあるが実体が無い参照は「共有ライブラリ参照（未取得）」として欠落報告する。
+- render-cut / edit-lint は依存ゼロ CLI のため、解決ロジックは各パッケージ内に**同一実装を重複**して
+  持つ（`src/library-reference.mjs`）。挙動同一性は両テストの同一ケース表で担保する。
+
+## 3. 使い方（CLI）
+
+```sh
+# 参照モードで取得（コピーせず台帳へ記帳。既定は従来どおりコピー）
+akari-assets fetch <id> --project <dir> --reference
+
+# 「素材をまとめる」— 参照の実体化（持ち出し・アーカイブ用）
+akari-assets bundle --project <dir> [--dry-run]
+```
+
+bundle は台帳の各参照をキャッシュから `assets/<category>/<id>/` へ実体化して台帳から除去する。
+未取得の参照は resolve（取得）を試み、取得できないものは台帳に残して部分成功（exit 非 0）で報告する。冪等。
+
+## 4. スコープ外（後続）
+
+- シェル UI の採用（取り込みフローの reference 既定化・プロジェクト面の「参照」バッジ・
+  プレビュー経路のフォールバック）
+- 共有キャッシュの容量管理 UI
+
+出自: 2026-09-02 の素材パネル再設計ラウンドの裁定 3（実体 = 共有キャッシュ・プロジェクトには参照・
+持ち出しは「素材をまとめる」で閉じる）。

package/vendor/docs/contract-2026-09-02-captions-style-preset-v0.md

@@ -79,6 +79,22 @@ edit-lint はカタログを読める環境だけ存在検査を行い、未知
 
 - ルートレベルの `style_preset`
 - price、購入状態、👑 プレミア、Lab 接続
-- テンプレピッカー UI と選択行への一括適用 RPC（T6b）
 - 既存 merge 実装の統合・改修
 - テロップ契約との統合
+
+## 8. パネル側の約束（T6b）
+
+「台本」パネルの字幕テンプレピッカーは、行選択がある場合は選択行だけ、選択が無い場合は
+全行を適用先にする。全行適用はカード選択後の明示ボタンで確定する。
+
+書き戻しは `setCaptionStylePreset` RPC 1 回で対象行を一括更新し、1 回のファイル書き込みと
+1 git commit にまとめる。`text_style` は変更しない。`presetId: null` は `style_preset` キーだけを
+削除する解除操作である。同値の再適用は書き込みも commit も行わない。
+
+各行は `🎨 <テンプレ名>` バッジで参照中のテンプレを示す。カタログに無い id は
+`🎨 <id>?` と表示し、edit-lint warning と併用して読み込みや書き出しを壊さない。
+
+インスペクターはプリセット解決後の値を表示する。そこで個別の値を上書きすると
+`text_style` に保存され、以後そのフィールドはテンプレ更新に追従しない。
+
+👑、price、Lab 接続、パネル内履歴、インスペクターの「テンプレ: xxx」表示は T6c / T9 の範囲とする。

package/vendor/docs/contract-2026-09-02-shape-item-v0.md

@@ -0,0 +1,49 @@
+# contract — 図形アイテム v0（edit.json v2 `shape` ソースとインライン SVG 降下）
+
+- 状態: 実装済み（データ契約 + edit-store 降下。パネル露出・インスペクター UI は後続）
+- 決定日: 2026-09-02
+- 実装: `packages/schemas/edit.schema.json`（`itemSourceShapeV2` / `itemV2Shape`）/
+  `packages/edit-store`（`src/shape-markup.ts`・`internal-model.ts`）
+
+## 1. 目的
+
+四角・線・矢印・吹き出しといった図形を、素材ファイル無しで edit.json v2 の第一級アイテムとして
+宣言できるようにする。レンダラは新設しない — edit-store の内部モデルが図形を**決定論的な
+インライン SVG を持つ html オーバーレイへ降下**させ、既存の html 経路（プレビュー・書き出しとも）が
+そのまま描く。
+
+## 2. 語彙 v0
+
+```json
+{ "id": "shape-1", "at": 0, "duration": 90,
+  "source": { "kind": "shape", "shape": "rect",
+              "params": { "width": 600, "height": 340, "fill": "#f97316" } } }
+```
+
+- `shape`: `rect | rounded-rect | ellipse | line | arrow | speech-bubble`
+- `params`（全部 optional・additionalProperties false で開始 — 広げる方向は互換）:
+  `width`（>0・既定 600）/ `height`（>0・既定 340。line / arrow は既定 80）/
+  `fill`（既定 `#f97316`）/ `stroke`（既定なし = 描かない）/ `strokeWidth`（≥0・既定 0。line / arrow は 8）/
+  `cornerRadius`（≥0・rounded-rect のみ・既定 24）
+- 色文字列は `^[#a-zA-Z0-9(),.%\s-]{1,64}$` に一致しないとき既定色へフォールバック
+  （SVG への注入封じ）。数値は有限数のみ受理・範囲外は既定へ。
+- 位置・拡大・不透明度・アニメはアイテム共通機構（`anchor` / `transform` / `opacity` /
+  `keyframes` / `motion` / `animator`）に委ね、params に重複ツマミを作らない。
+
+## 3. 降下の契約
+
+- `shapeMarkup(source)`（`packages/edit-store/src/shape-markup.ts`）は同一入力に対して
+  バイト同一の `<svg …>` 文字列を返す（時刻・乱数・環境非依存）。
+- 内部モデルは shape アイテムを html アイテムと同格に扱い、オーバーレイ宣言の `html` に
+  インラインマークアップを乗せる（`<` 始まりのため render-cut の `expandedHtmlOverlays` は
+  ファイル読込をせずそのまま通す）。
+- 既知の制約: SVG の xmlns URI が GPU 出口の適格性検査に absolute-external-url として
+  検知されるため、図形入りの書き出しは現状 **OSR 出口へフォールバック**する（描画は正しい）。
+  GPU 適格化（名前空間 URI の許可リスト化）は後続。
+
+## 4. スコープ外（後続）
+
+- 素材パネルの図形カテゴリ露出（現状は「近日」）・インスペクターの params ツマミ
+- スタンプ（新種別にしない — 画像素材で賄う）
+
+出自: 2026-09-02 の素材パネル再設計ラウンド（カテゴリ表「図形は種別追加から」）。

package/vendor/docs/contract-2026-09-02-word-book-v0.md

@@ -240,7 +240,7 @@ cloud）。
 | 瞬間 | 何をするか | 実装箇所 |
 |---|---|---|
 | 文字起こし直後 | 解決済み単語帳で全セグメントにプリパス（§3-2）。キャッシュ hit 経路も同じ | `packages/akari-tools/src/media/transcribe.mjs` `transcribeMedia`: `normalizeSegments` / `attachUnrecognizedSpans` の後・`recordTranscribe` の前。`options.wordBook`（`--no-word-book` / `--word-book <path>`） |
-| 台本パネル「覚える」 | 人が行を直した直後に、直した語列を `variants`、直した後を `surface` として登録を提案。**登録先の層を必ず人に確認**（既定 `project`。`channel` / `workspace` は昇格 = 内部契約 §4 の承認ゲート）。登録後、同じプロジェクトの `edited: false` な行と transcript に即時再適用し件数を返す | `apps/shell/extensions/akari-transcript` の node 側 service に `rememberWord` RPC を足し、`packages/word-book` の add + apply を呼ぶ |
+| 台本パネル「覚える」 | 人が行を直した直後に、直した語列を `variants`、直した後を `surface` として登録を提案。**登録先の層を必ず人に確認**（既定 `project`。`channel` / `workspace` は昇格 = 内部契約 §4 の承認ゲート）。登録後、同じプロジェクトの `edited: false` な行と transcript に即時再適用し件数を返す | `apps/shell/extensions/akari-transcript` の node 側 service に `rememberWord` RPC を足し、`packages/word-book` の add + apply を呼ぶ（訂正 2026-09-02: RPC は akari-annotations の service に足す。UI は akari-transcript） |
 | 手動再適用 | 既存プロジェクトに解決済み単語帳を当て直す。`--dry-run` で件数だけ | `akari word-book apply [--project <dir>] [--dry-run]` |
 | edit-lint | §5 の規則 | `packages/edit-lint/src/edit-lint.mjs`（captions 検査の並び） |
 | 行分割 | §3-6 の軟らかい供給 | `resolveCaptionDisplay` の呼び出し 4 箇所 |
@@ -400,3 +400,5 @@ lint の一致も §3-2 と同じ語境界規則（`words[]` → 無ければ `I
 6. 作業場 fixture（`root.json` + `channels/<c>/videos/<p>`）で `resolve` が 4 層の出所を正しく返し、
    作業場なし fixture で `project` + `builtin` に落ちること
 7. 実際のホーム・作業場へ書き込まない（全テストは一時ディレクトリと `AKARI_WORD_BOOK` で完結）
+8. launcher: `akari word-book --help` が 4 サブコマンド（resolve / validate / add / apply）を列挙し、
+   akari-tools 不在時は「インストール方法」を示して exit 1

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

@@ -1,6 +1,6 @@
 {
   "name": "akari-video",
-  "version": "0.1.34",
+  "version": "0.1.36",
   "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/bin/akari-assets.mjs

@@ -1,12 +1,14 @@
 #!/usr/bin/env node
-// akari-assets — 素材 resolver v0 の CLI（list / fetch / sync / browse）。
+// akari-assets — 素材 resolver v0 の CLI（list / fetch / bundle / sync / browse）。
 //
 //   akari-assets list [--category <c>] [--json]
-//   akari-assets fetch <id> [--project <dir>] [--force]
+//   akari-assets fetch <id> [--project <dir>] [--reference] [--force]
+//   akari-assets bundle --project <dir> [--dry-run]
 //   akari-assets sync
 //   akari-assets browse [--port <n>]
 
 import { startBrowseServer } from '../src/browse-server.mjs';
+import { bundleProjectReferences } from '../src/bundle.mjs';
 import { cacheCatalog, loadCatalog } from '../src/catalog.mjs';
 import { resolve as resolveAsset } from '../src/resolve.mjs';
 import { composeState } from '../src/state.mjs';
@@ -43,22 +45,66 @@ async function cmdList(args, env) {
 async function cmdFetch(args, env) {
   const id = args[0];
   if (!id || id.startsWith('--')) {
-    console.error('使い方: akari-assets fetch <id> [--project <dir>] [--force]');
+    console.error('使い方: akari-assets fetch <id> [--project <dir>] [--reference] [--force]');
     process.exitCode = 1;
     return;
   }
   const project = flagValue(args, '--project');
+  const reference = args.includes('--reference');
   const force = args.includes('--force');
+  if (reference && !project) {
+    console.error('--reference には --project <dir> が必要です');
+    process.exitCode = 1;
+    return;
+  }
   try {
-    const result = await resolveAsset(id, { env, project, force });
+    const result = await resolveAsset(id, { env, project, force, reference });
     console.log(`${result.cached ? '取得済み（キャッシュ）を使用' : '取得しました'}: ${result.dir}`);
     if (result.projectDir) console.log(`  プロジェクトへコピー: ${result.projectDir}`);
+    if (result.referenced) console.log(`  参照を記帳: ${result.category}/${result.id}`);
   } catch (error) {
     console.error(error instanceof Error ? error.message : String(error));
     process.exitCode = 1;
   }
 }
 
+async function cmdBundle(args, env) {
+  const project = flagValue(args, '--project');
+  const dryRun = args.includes('--dry-run');
+  if (!project) {
+    console.error('使い方: akari-assets bundle --project <dir> [--dry-run]');
+    process.exitCode = 1;
+    return;
+  }
+
+  const result = await bundleProjectReferences({ project, env, dryRun });
+  if (result.planned.length === 0) {
+    console.log('実体化する参照はありません');
+    return;
+  }
+  if (dryRun) {
+    for (const reference of result.planned) {
+      console.log(`実体化予定: ${reference.category}/${reference.id}`);
+    }
+    return;
+  }
+
+  for (const materialized of result.materialized) {
+    console.log(
+      `実体化しました: ${materialized.category}/${materialized.id} -> ${materialized.projectDir}`,
+    );
+  }
+  if (result.failures.length > 0) {
+    console.error(`実体化できなかった参照 ${result.failures.length} 件:`);
+    for (const failure of result.failures) {
+      console.error(
+        `  ${failure.reference.category}/${failure.reference.id}: ${failure.message}`,
+      );
+    }
+    process.exitCode = 1;
+  }
+}
+
 async function cmdSync(_args, env) {
   const catalog = await loadCatalog({ env });
   await cacheCatalog(env, catalog);
@@ -72,10 +118,12 @@ async function cmdBrowse(args, env) {
 }
 
 function printUsage() {
-  console.log(`使い方: akari-assets <list|fetch|sync|browse> [options]
+  console.log(`使い方: akari-assets <list|fetch|bundle|sync|browse> [options]
 
   list [--category <c>] [--json]          合成カタログ一覧（取得状態バッジ込み）
-  fetch <id> [--project <dir>] [--force]  素材を解決してローカルへ登録（キャッシュ済みなら即返す）
+  fetch <id> [--project <dir>] [--reference] [--force]
+                                          素材を解決して登録（--reference はコピーせず参照を記帳）
+  bundle --project <dir> [--dry-run]      参照素材をプロジェクトへ実体化（素材をまとめる）
   sync                                    カタログを取得してローカルにキャッシュ（オフライン用）
   browse [--port <n>]                     ローカル HTTP サーバでカタログを閲覧・投入（既定 8910）
 
@@ -92,6 +140,7 @@ async function main() {
 
   if (sub === 'list') return cmdList(rest, env);
   if (sub === 'fetch') return cmdFetch(rest, env);
+  if (sub === 'bundle') return cmdBundle(rest, env);
   if (sub === 'sync') return cmdSync(rest, env);
   if (sub === 'browse') return cmdBrowse(rest, env);
 

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

@@ -0,0 +1,43 @@
+import { resolveAkariHome } from './env.mjs';
+import { isAssetCached, localAssetDir } from './library.mjs';
+import { readProjectReferences, removeProjectReference } from './project-references.mjs';
+import { copyIntoProject, resolve as resolveAsset } from './resolve.mjs';
+
+export async function bundleProjectReferences({
+  project,
+  env = process.env,
+  dryRun = false,
+} = {}) {
+  const planned = await readProjectReferences(project);
+  const result = { planned, materialized: [], failures: [] };
+  if (dryRun) return result;
+
+  const home = resolveAkariHome(env);
+  for (const reference of planned) {
+    try {
+      if (!isAssetCached(home, reference.category, reference.id)) {
+        const resolved = await resolveAsset(reference.id, { env });
+        if (resolved.category !== reference.category) {
+          throw new Error(
+            `カタログのカテゴリが台帳と一致しません: ${reference.category}/${reference.id}（実際: ${resolved.category}）`,
+          );
+        }
+      }
+      const sourceDir = localAssetDir(home, reference.category, reference.id);
+      const projectDir = await copyIntoProject(
+        sourceDir,
+        project,
+        reference.category,
+        reference.id,
+      );
+      await removeProjectReference(project, reference);
+      result.materialized.push({ ...reference, projectDir });
+    } catch (error) {
+      result.failures.push({
+        reference,
+        message: error instanceof Error ? error.message : String(error),
+      });
+    }
+  }
+  return result;
+}

package/vendor/packages/asset-resolver/src/project-references.mjs

@@ -0,0 +1,131 @@
+import { randomUUID } from 'node:crypto';
+import { lstatSync, realpathSync } from 'node:fs';
+import { mkdir, readFile, rename, rm, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+
+const REFERENCES_FILE = path.join('.akari', 'asset-references.json');
+
+// 参照台帳（.akari/asset-references.json）のスキーマ版数。edit.json の version とは無関係。
+const REFERENCES_SCHEMA_VERSION = 0;
+
+function compareReferences(left, right) {
+  if (left.category !== right.category) return left.category < right.category ? -1 : 1;
+  if (left.id !== right.id) return left.id < right.id ? -1 : 1;
+  return 0;
+}
+
+function isReference(value) {
+  return value !== null
+    && typeof value === 'object'
+    && !Array.isArray(value)
+    && typeof value.id === 'string'
+    && value.id.length > 0
+    && typeof value.category === 'string'
+    && value.category.length > 0;
+}
+
+function normalizeReferences(value) {
+  const source = Array.isArray(value) ? value : value?.references;
+  if (!Array.isArray(source)) return [];
+  const unique = new Map();
+  for (const entry of source) {
+    if (!isReference(entry)) continue;
+    const reference = { id: entry.id, category: entry.category };
+    unique.set(`${reference.category}\0${reference.id}`, reference);
+  }
+  return [...unique.values()].sort(compareReferences);
+}
+
+function assertReference(reference) {
+  if (!isReference(reference)) {
+    throw new TypeError('asset reference requires non-empty id and category strings');
+  }
+}
+
+function referencesPath(projectDir) {
+  return path.join(path.resolve(projectDir), REFERENCES_FILE);
+}
+
+async function writeProjectReferences(projectDir, references) {
+  const target = referencesPath(projectDir);
+  await mkdir(path.dirname(target), { recursive: true });
+  const temp = `${target}.${process.pid}.${randomUUID()}.tmp`;
+  const body = `${JSON.stringify({ version: REFERENCES_SCHEMA_VERSION, references: normalizeReferences(references) }, null, 2)}\n`;
+  try {
+    await writeFile(temp, body, { encoding: 'utf8', flag: 'wx' });
+    await rename(temp, target);
+  } finally {
+    await rm(temp, { force: true }).catch(() => {});
+  }
+}
+
+export async function readProjectReferences(projectDir) {
+  try {
+    const parsed = JSON.parse(await readFile(referencesPath(projectDir), 'utf8'));
+    if (parsed?.version !== REFERENCES_SCHEMA_VERSION) return [];
+    return normalizeReferences(parsed);
+  } catch {
+    return [];
+  }
+}
+
+export async function recordProjectReference(projectDir, reference) {
+  assertReference(reference);
+  const references = await readProjectReferences(projectDir);
+  references.push({ id: reference.id, category: reference.category });
+  const normalized = normalizeReferences(references);
+  await writeProjectReferences(projectDir, normalized);
+  return normalized;
+}
+
+export async function removeProjectReference(projectDir, reference) {
+  assertReference(reference);
+  const references = (await readProjectReferences(projectDir)).filter(
+    (entry) => entry.id !== reference.id || entry.category !== reference.category,
+  );
+  await writeProjectReferences(projectDir, references);
+  return references;
+}
+
+function parseDeclaredAssetPath(declaredPath) {
+  if (typeof declaredPath !== 'string' || declaredPath.length === 0 || path.isAbsolute(declaredPath)) return null;
+  const normalized = declaredPath.replaceAll('\\', '/');
+  const segments = normalized.split('/');
+  if (segments.length < 4
+      || segments[0] !== 'assets'
+      || segments.some((segment) => segment === '' || segment === '.' || segment === '..')) {
+    return null;
+  }
+  return {
+    category: segments[1],
+    id: segments[2],
+    rest: segments.slice(3),
+  };
+}
+
+function isWithin(root, target) {
+  const relative = path.relative(root, target);
+  return relative === '' || (!relative.startsWith('..') && !path.isAbsolute(relative));
+}
+
+export function resolveLibraryFallback({ declaredPath, references, akariAssetsDir }) {
+  const parsed = parseDeclaredAssetPath(declaredPath);
+  if (!parsed || typeof akariAssetsDir !== 'string' || akariAssetsDir.length === 0) return null;
+  const normalizedReferences = normalizeReferences(references);
+  if (!normalizedReferences.some(
+    (entry) => entry.category === parsed.category && entry.id === parsed.id,
+  )) return null;
+
+  const lexicalRoot = path.resolve(akariAssetsDir);
+  const lexicalTarget = path.resolve(lexicalRoot, parsed.category, parsed.id, ...parsed.rest);
+  if (!isWithin(lexicalRoot, lexicalTarget)) return null;
+
+  try {
+    const actualRoot = realpathSync(lexicalRoot);
+    const actualTarget = realpathSync(lexicalTarget);
+    if (!isWithin(actualRoot, actualTarget) || !lstatSync(actualTarget).isFile()) return null;
+    return actualTarget;
+  } catch {
+    return null;
+  }
+}