akari-video 1.3.0-beta.2 → 1.3.0-beta.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "akari-video",
-  "version": "1.3.0-beta.2",
+  "version": "1.3.0-beta.4",
   "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/vendor/packages/akari-launcher/package.json

@@ -1,6 +1,6 @@
 {
   "name": "akari-video",
-  "version": "1.3.0-beta.2",
+  "version": "1.3.0-beta.4",
   "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/overlay-runtime/src/interaction.js

@@ -422,6 +422,8 @@ function elementBoxCompanions(style, parentStyle, width, height) {
   let selectedId = null;
   let selectedIds = [];
   let elementFocus = null;
+  // Inner selection belongs only to the currently selected telop, never to edit.json.
+  let telopInnerId = null;
   let elementGeometryCache = null;
   let elementNudge = null;
   let elementNudgeTimer = null;
@@ -1819,8 +1821,11 @@ function elementBoxCompanions(style, parentStyle, width, height) {
 
   function clearSelection() {
     const hadElementFocus = window.akari.capabilities?.elementSelection === true && Boolean(selectedElementFocus());
+    const hadTelopSelection = window.akari.capabilities?.elementSelection === true
+      && selectedOverlay && isTelopOverlay(selectedOverlay);
     flushElementNudge();
     elementFocus = null;
+    telopInnerId = null;
     if (activeRotate) cancelRotate();
     if (activeLine) finishLineEndpoint(true);
     flushNudge();
@@ -1839,7 +1844,7 @@ function elementBoxCompanions(style, parentStyle, width, height) {
     selectionFrame?.remove();
     selectionFrame = null;
     hideSnapGuides();
-    if (hadElementFocus) renderScopeBreadcrumb();
+    if (hadElementFocus || hadTelopSelection) renderScopeBreadcrumb();
   }
 
   function handleSelectedOverlayUnavailable(container) {
@@ -1879,24 +1884,41 @@ function elementBoxCompanions(style, parentStyle, width, height) {
         selectedOverlay.setAttribute('data-akari-interaction-selected', 'true');
         reconcileElementFocus();
       } else {
+        const keepTelopInner = selectedId === nextId && telopInnerId === nextId
+          && selectedIds.length === 1 && !groupSelection;
         clearSelection();
         selectedOverlay = container;
         selectedId = nextId;
         selectedIds = selectedId === null ? [] : [selectedId];
+        if (keepTelopInner) telopInnerId = nextId;
         selectedOverlay.setAttribute("data-akari-interaction-selected", "true");
       }
     }
 
     refreshSelectionFrame();
+    if (window.akari.capabilities?.elementSelection === true && isTelopOverlay(selectedOverlay)) renderScopeBreadcrumb();
     startSelectionTracking();
     return true;
   }
 
-  function canFocusElement(container) {
+  function elementSelectionEnabled(container) {
     if (window.akari.capabilities?.elementSelection !== true || !container || selectedIds.length > 1) return false;
     return window.akari.state?.summary?.overlays?.some(overlay => overlay.id === container.dataset.overlayId
       && overlay.elementSelection === true) === true;
   }
+  function canFocusElement(container) {
+    return elementSelectionEnabled(container)
+      && (!isTelopOverlay(container) || telopInnerId === selectedId && selectedId === container.dataset.overlayId);
+  }
+  function setTelopInnerSelection(overlayId, inner) {
+    if (typeof overlayId !== 'string' || selectedId !== overlayId || selectedIds.length !== 1
+      || groupSelection || !selectedOverlay || !isTelopOverlay(selectedOverlay)
+      || !elementSelectionEnabled(selectedOverlay)) return false;
+    telopInnerId = inner === true ? overlayId : null;
+    if (!telopInnerId && selectedElementFocus()) focusElement(null);
+    hideHover();
+    return true;
+  }
   function focusedElement() {
     if (!selectedElementFocus() || !selectedOverlay) return null;
     const root = fragmentRoot(selectedOverlay);
@@ -1929,6 +1951,7 @@ function elementBoxCompanions(style, parentStyle, width, height) {
     const ref = element && elementAddress(root, element);
     const next = ref ? { overlayId: selectedId, ref, tag: element.tagName.toLowerCase(),
       label: elementLabel(root, element) } : null;
+    if (!next && telopInnerId === selectedId) telopInnerId = null;
     if (elementFocus?.ref === next?.ref && elementFocus?.overlayId === next?.overlayId) return;
     flushElementNudge();
     elementFocus = next;
@@ -2063,7 +2086,8 @@ function elementBoxCompanions(style, parentStyle, width, height) {
     clearBreadcrumbHover();
     const entries = [];
     const append = (label, action, target) => entries.push({ label, action, target });
-    if (selectedElementFocus() && selectedOverlay) {
+    if (selectedOverlay && (selectedElementFocus() || window.akari.capabilities?.elementSelection === true
+      && selectedIds.length === 1 && isTelopOverlay(selectedOverlay))) {
       append('全体', () => { clearSelection(); publishScopedSelection(); }, { kind: 'stage' });
       for (const id of lineage(selectionTree(), scopeId)) {
         append(treeNode(id)?.label ?? id, () => applyScopedSelection({ selectId: id, scopeId: treeNode(id)?.parentId ?? null }),
@@ -4383,7 +4407,8 @@ function elementBoxCompanions(style, parentStyle, width, height) {
       if (activeEdit?.container === hit && eventHitsElement(event, activeEdit.element)) return;
       clickOrigin.scopedHit = true;
       if (activeEdit) void commitEdit();
-      if (window.akari.capabilities?.elementSelection === true && event.isTrusted && !event.shiftKey) {
+      if (window.akari.capabilities?.elementSelection === true && event.isTrusted && !event.shiftKey
+        && (!isTelopOverlay(hit) || canFocusElement(hit))) {
         const root = fragmentRoot(hit);
         const target = event.target instanceof Element && root?.contains(event.target)
           ? nearestSelectableElement(root, event.target, stage?.getBoundingClientRect(), selectionOptions(root)) : null;
@@ -4404,7 +4429,8 @@ function elementBoxCompanions(style, parentStyle, width, height) {
         const focused = focusedElement();
         if (focused && isSelectionContainer(focused) && focused.contains(event.target)) {
           clickOrigin.preservedContainer = true;
-        } else if (clickOrigin?.hitId === selectedId) {
+        } else if ((!isTelopOverlay(selectedOverlay) || canFocusElement(selectedOverlay))
+          && clickOrigin?.hitId === selectedId) {
           focusElement(elementByAddress(fragmentRoot(selectedOverlay), clickOrigin.elementRef));
         } else focusElementAt(selectedOverlay, event);
       } else if (selectedElementFocus()) focusElement(null);
@@ -5209,7 +5235,9 @@ function elementBoxCompanions(style, parentStyle, width, height) {
     if (window.akari.capabilities?.elementSelection === true
       && event.isTrusted && !event.shiftKey && selectedOverlay) {
       if (clickOrigin?.preservedContainer) focusElementAt(selectedOverlay, event);
-      else if (!nextId && clickOrigin?.hitId === selectedId) {
+      else if ((!isTelopOverlay(selectedOverlay) || canFocusElement(selectedOverlay))
+        && (!nextId || isTelopOverlay(selectedOverlay) && telopInnerId === selectedId
+          && nextId === selectedId) && clickOrigin?.hitId === selectedId) {
         focusElement(elementByAddress(fragmentRoot(selectedOverlay), clickOrigin.elementRef));
       } else focusElementAt(selectedOverlay, event);
     }
@@ -5288,10 +5316,12 @@ function elementBoxCompanions(style, parentStyle, width, height) {
       }
     }
     if (event.key === 'Enter' && !event.shiftKey && !activeEdit && !selectedElementFocus()
-      && selectedOverlay && canFocusElement(selectedOverlay)) {
+      && selectedOverlay && elementSelectionEnabled(selectedOverlay)
+      && (!isTelopOverlay(selectedOverlay) || selectedIds.length === 1)) {
       const root = fragmentRoot(selectedOverlay);
       const first = firstSelectableElement(root, stage?.getBoundingClientRect(), selectionOptions(root));
       if (first) {
+        if (isTelopOverlay(selectedOverlay)) telopInnerId = selectedId;
         focusElement(first);
         event.preventDefault(); event.stopPropagation(); event.stopImmediatePropagation();
         return;
@@ -5339,7 +5369,8 @@ function elementBoxCompanions(style, parentStyle, width, height) {
         if (groupSelection) {
           applyScopedSelection(enterScope(selectionTree(), selectedId)); handled(); return;
         }
-        if (selectedOverlay) {
+        if (selectedOverlay && (!isTelopOverlay(selectedOverlay)
+          || telopInnerId === selectedId && Boolean(selectedElementFocus()))) {
           const root = fragmentRoot(selectedOverlay);
           const text = root && [root, ...root.querySelectorAll('*')].find(canEditText);
           if (text) { beginEdit(selectedOverlay, text); handled(); }
@@ -5827,6 +5858,9 @@ function elementBoxCompanions(style, parentStyle, width, height) {
     releasePointerOwner,
     get selectedId() { return selectedId; },
     get elementFocus() { return selectedElementFocus(); },
+    get selectedTelop() { return Boolean(selectedOverlay && selectedIds.length === 1 && isTelopOverlay(selectedOverlay)); },
+    get telopInner() { return telopInnerId !== null && telopInnerId === selectedId; },
+    setTelopInnerSelection,
     clearElementFocus() { if (selectedElementFocus()) focusElement(null, { notify: false }); },
     focusElementAtPoint,
     get selectedIds() { return [...selectedIds]; },

package/vendor/packages/overlay-runtime/src/three-runtime.js

@@ -43,6 +43,7 @@ window.akari.threeRuntime = (() => {
     "lights",
     "animationClip",
     "materialOverrides",
+    "finishes",
     "shadows",
     "texts",
     "physics",
@@ -136,6 +137,56 @@ window.akari.threeRuntime = (() => {
   const VIDEO_TEXTURE_PATTERN = /^data:video\/|\.(?:mp4|m4v|mov|webm)(?:[?#]|$)/i;
   const CSS_VAR_REFERENCE_PATTERN = /^var\(\s*(--[\w-]+)\s*\)$/;
   const CSS_CUSTOM_PROPERTY_PATTERN = /^--[A-Za-z_][A-Za-z0-9_-]*$/;
+  const FINISH_NAME_PATTERN = /^[A-Za-z_][A-Za-z0-9_-]*$/;
+  const FINISH_COLOR_PATTERN = /^#[0-9a-fA-F]{6}$/;
+  const FINISH_PROPERTIES = new Set([
+    "color", "metalness", "roughness", "clearcoat", "clearcoatRoughness", "emissive",
+  ]);
+
+  function validateFinishes(finishes) {
+    const isObject = (value) => value !== null && typeof value === "object" && !Array.isArray(value);
+    if (!isObject(finishes) || Object.keys(finishes).some((key) => !["var", "default", "options"].includes(key))) {
+      throw new TypeError("finishes は var / default / options を指定する object である必要があります");
+    }
+    if (finishes.var !== undefined
+      && (typeof finishes.var !== "string" || !CSS_CUSTOM_PROPERTY_PATTERN.test(finishes.var))) {
+      throw new TypeError("finishes.var は -- で始まる CSS カスタムプロパティ名である必要があります");
+    }
+    if (typeof finishes.default !== "string" || !FINISH_NAME_PATTERN.test(finishes.default)) {
+      throw new TypeError("finishes.default は有効な選択名である必要があります");
+    }
+    if (!isObject(finishes.options) || Object.keys(finishes.options).length === 0) {
+      throw new TypeError("finishes.options は非空の object である必要があります");
+    }
+    for (const [name, materials] of Object.entries(finishes.options)) {
+      if (!FINISH_NAME_PATTERN.test(name)) {
+        throw new TypeError(`finishes.options の選択名が不正です: ${name}`);
+      }
+      if (!isObject(materials)) {
+        throw new TypeError(`finishes.options.${name} は材質名をキーとする object である必要があります`);
+      }
+      for (const [materialName, values] of Object.entries(materials)) {
+        if (!materialName.trim() || !isObject(values)) {
+          throw new TypeError(`finishes.options.${name} の材質指定が不正です: ${materialName}`);
+        }
+        for (const [key, value] of Object.entries(values)) {
+          if (!FINISH_PROPERTIES.has(key)) {
+            throw new TypeError(`finishes.options.${name}.${materialName} の未対応キーです: ${key}`);
+          }
+          if (key === "color" || key === "emissive") {
+            if (typeof value !== "string" || !FINISH_COLOR_PATTERN.test(value)) {
+              throw new TypeError(`finishes.options.${name}.${materialName}.${key} は 6 桁 hex 色である必要があります`);
+            }
+          } else if (typeof value !== "number" || !Number.isFinite(value) || value < 0 || value > 1) {
+            throw new TypeError(`finishes.options.${name}.${materialName}.${key} は 0〜1 の有限数である必要があります`);
+          }
+        }
+      }
+    }
+    if (!Object.hasOwn(finishes.options, finishes.default)) {
+      throw new TypeError("finishes.default は finishes.options 内の選択名である必要があります");
+    }
+  }
 
   function finiteNumber(value, fallback) {
     const number = Number(value);
@@ -570,6 +621,7 @@ window.akari.threeRuntime = (() => {
         throw new TypeError(`data-akari-3d-scene の未対応キーです: ${key}`);
       }
     }
+    if (descriptor.finishes !== undefined) validateFinishes(descriptor.finishes);
     // texts[] があれば model は任意化される（両方あれば併存。§3.1）
     const hasTexts = descriptor.texts !== undefined;
     if (hasTexts) {
@@ -946,6 +998,102 @@ window.akari.threeRuntime = (() => {
     }));
   }
 
+  function initializeFinishes(instance, root) {
+    if (!instance.finish) return;
+    const materialsByName = new Map();
+    root.traverse((object) => {
+      const materials = Array.isArray(object.material) ? object.material : object.material ? [object.material] : [];
+      for (const material of materials) {
+        if (!materialsByName.has(material.name)) materialsByName.set(material.name, new Set());
+        materialsByName.get(material.name).add(material);
+      }
+    });
+    // materialOverrides 適用後の値を素の値として記録し、finishes は指定キーだけ上書きする。
+    // emissiveMap / emissiveIntensity は記録対象にも上書き対象にも含めず保持する。
+    for (const materials of materialsByName.values()) {
+      for (const material of materials) {
+        instance.finish.base.set(material, {
+          color: material.color?.clone(),
+          metalness: material.metalness,
+          roughness: material.roughness,
+          clearcoat: material.clearcoat,
+          clearcoatRoughness: material.clearcoatRoughness,
+          emissive: material.emissive?.clone(),
+        });
+      }
+    }
+    instance.finish.materialsByName = materialsByName;
+    applyFinish(instance);
+  }
+
+  function applyFinish(instance) {
+    const state = instance.finish;
+    if (!state || !state.materialsByName) return;
+    const { descriptor } = state;
+    const raw = getComputedStyle(instance.canvas).getPropertyValue(descriptor.var ?? "--akari-3d-finish").trim();
+    const requested = raw.replace(/^(['"])(.*)\1$/, "$2");
+    const selected = requested === "" ? descriptor.default
+      : Object.hasOwn(descriptor.options, requested) ? requested : descriptor.default;
+    if (requested !== "" && !Object.hasOwn(descriptor.options, requested)
+      && !state.warnedValues.has(requested)) {
+      state.warnedValues.add(requested);
+      console.warn(`[akari-three] finishes の未知の選択値です: ${requested}。${descriptor.default} を使います`);
+    }
+    if (state.selected === selected) return;
+
+    const oldCoats = new Map();
+    for (const [material, base] of state.base) {
+      oldCoats.set(material, material.clearcoat);
+      if (base.color && material.color) material.color.copy(base.color);
+      if (base.emissive && material.emissive) material.emissive.copy(base.emissive);
+      for (const key of ["metalness", "roughness", "clearcoat", "clearcoatRoughness"]) {
+        if (base[key] !== undefined && key in material) material[key] = base[key];
+      }
+    }
+    const applied = [];
+    for (const [name, values] of Object.entries(descriptor.options[selected])) {
+      const materials = state.materialsByName.get(name);
+      if (!materials?.size) {
+        const warningKey = JSON.stringify([selected, name]);
+        if (!state.warnedMaterials.has(warningKey)) {
+          state.warnedMaterials.add(warningKey);
+          console.warn(`[akari-three] finishes の対象が見つかりません: ${name}（選択: ${selected}）`);
+        }
+        applied.push({ material: name, applied: false });
+        continue;
+      }
+      for (const material of materials) {
+        for (const [key, value] of Object.entries(values)) {
+          if (!(key in material) || ((key === "color" || key === "emissive") && !material[key]?.set)) {
+            const warningKey = `${material.uuid}:${key}`;
+            if (!state.warnedProperties.has(warningKey)) {
+              state.warnedProperties.add(warningKey);
+              console.warn(`[akari-three] finishes の ${name}.${key} はこの材質に適用できません`);
+            }
+            continue;
+          }
+          if (key === "color" || key === "emissive") material[key].set(value);
+          else material[key] = value;
+        }
+        applied.push({
+          material: name, applied: true,
+          color: material.color ? `#${material.color.getHexString()}` : null,
+          metalness: material.metalness ?? null,
+          roughness: material.roughness ?? null,
+          clearcoat: material.clearcoat ?? null,
+          clearcoatRoughness: material.clearcoatRoughness ?? null,
+          emissive: material.emissive ? `#${material.emissive.getHexString()}` : null,
+        });
+      }
+    }
+    // clearcoat の有無だけがシェーダ定義を変えうる。色・係数の通常変更では再コンパイルしない。
+    for (const [material, oldCoat] of oldCoats) {
+      if ((oldCoat > 0) !== (material.clearcoat > 0)) material.needsUpdate = true;
+    }
+    state.selected = selected;
+    state.applied = applied;
+  }
+
   function createCamera(THREE, descriptor) {
     const cameraDescriptor = descriptor.camera ?? {};
     const camera = new THREE.PerspectiveCamera(
@@ -2017,6 +2165,7 @@ window.akari.threeRuntime = (() => {
     if (!instance.active || !instance.contentReady) return;
     rendererSize(instance, instance.maxRenderSize);
     applyProjectionKnobs(instance);
+    applyFinish(instance);
     if (instance.mixer) instance.mixer.setTime(Math.max(0, localSeconds));
     if (instance.textAnimEntries.length > 0) updateTextVisibility(instance, localSeconds);
     if (instance.textAnimEntries.length > 0) updateTextAnimations(instance, localSeconds);
@@ -2379,6 +2528,16 @@ window.akari.threeRuntime = (() => {
       physicsPresimMs: null,
       // materialOverrides の解決結果（inspect() から検証・証跡に使う）。
       materialOverrideReport: [],
+      finish: descriptor.finishes ? {
+        descriptor: descriptor.finishes,
+        selected: null,
+        applied: [],
+        base: new Map(),
+        materialsByName: null,
+        warnedValues: new Set(),
+        warnedMaterials: new Set(),
+        warnedProperties: new Set(),
+      } : null,
       // model 読み込み（宣言時のみ）+ 全 texts sync() 完了の両方が揃うまで false。
       // draw() はこれを ready 条件に使う（読み込み中フレームが書き出しに混入しないため）
       contentReady: false,
@@ -2410,6 +2569,9 @@ window.akari.threeRuntime = (() => {
       }
       instance.model = gltf.scene;
       await applyMaterialOverrides(THREE, instance, gltf.scene, descriptor.materialOverrides);
+      // materialOverrides を先に適用し、その結果を素の値として finishes が指定キーだけ上書きする。
+      // emissiveMap / emissiveIntensity は materialOverrides、emissive 色は finishes の担当。
+      initializeFinishes(instance, gltf.scene);
       if (descriptor.environment?.map) {
         await applyEnvironmentMap(THREE, instance, descriptor.environment.map);
       }
@@ -2623,6 +2785,8 @@ window.akari.threeRuntime = (() => {
             if (rows.has(material.uuid)) continue;
             rows.set(material.uuid, {
               name: material.name, type: material.type, metalness: material.metalness,
+              color: material.color ? `#${material.color.getHexString()}` : null,
+              emissive: material.emissive ? `#${material.emissive.getHexString()}` : null,
               roughness: material.roughness, specularIntensity: material.specularIntensity,
               clearcoat: material.clearcoat, clearcoatRoughness: material.clearcoatRoughness,
               emissiveIntensity: material.emissiveIntensity,
@@ -2633,6 +2797,12 @@ window.akari.threeRuntime = (() => {
       })(),
       // materialOverrides の CSS 変数解決・適用結果（検証・証跡用）。
       materialOverrides: instance.materialOverrideReport.map((entry) => ({ ...entry })),
+      finish: instance.finish ? {
+        var: instance.finish.descriptor.var ?? "--akari-3d-finish",
+        selected: instance.finish.selected,
+        default: instance.finish.descriptor.default,
+        applied: instance.finish.applied.map((entry) => ({ ...entry })),
+      } : null,
       // texts[] の per-char 展開数（検証・証跡用。flat モードの読み込み完了を絵の比較なしに確認する）
       textNodes: instance.textNodes.length,
       textBlocks: instance.textAnimEntries.length,

package/vendor/skills/overlay-authoring/3d.md

@@ -87,7 +87,7 @@ fragment は単一ルートとし、透明 canvas、任意の静的 fallback、
 </div>
 ```
 
-- top-level key は `model` / `camera` / `environment` / `fog` / `background` / `lights` / `animationClip` / `materialOverrides` / `shadows` / `texts` / `physics` だけ。`texts[]` があれば `model` は任意（詳細は後述「texts[] — 3D テキスト」節）。`physics` は `texts[]` の物理落下（後述「physics — 3D テキストの物理落下」節）。
+- top-level key は `model` / `camera` / `environment` / `fog` / `background` / `lights` / `animationClip` / `materialOverrides` / `finishes` / `shadows` / `texts` / `physics` だけ。`texts[]` があれば `model` は任意（詳細は後述「texts[] — 3D テキスト」節）。`physics` は `texts[]` の物理落下（後述「physics — 3D テキストの物理落下」節）。
 - `model` は edit.json のあるディレクトリからの相対 `.glb` パス。URL や CDN を書かない。
 - camera は perspective camera。`position` / `lookAt` は `[x, y, z]`、`fov` / `near` / `far` は数値。
   または `{ "fromModel": "<glb 内カメラノード名>" }` で glb 内カメラを描画に使う（§カメラを動かす）。
@@ -120,7 +120,7 @@ fragment は単一ルートとし、透明 canvas、任意の静的 fallback、
   `"*"` も指定できる。省略時は静的シーンを描画する。Blender の glTF 書き出しはオブジェクトごとに
   clip を分けるので、1 個のモデルに複数の動きがあるときは `"*"` で束ねる（1 本しか再生しないと
   片方しか動かない）。存在しない clip 名を書いた場合はエラーになる。
-- `materialOverrides` は `{ "<material 名>": { "texture": "<画像または動画の相対パス>" } }` の形で、名前が一致するマテリアルの `emissiveMap` を差し替える。**差し替え先が `emissiveMap` である以上、貼り先の材質が発光しない（glTF の `emissiveFactor` が未設定 = 黒）と「0 × テクスチャ」で何も出ない**（2026-08-14 実害。詳細は後述「発光しない材質には貼れない」）。edit.json のあるディレクトリからの相対 PNG / JPEG / WebP 等、または MP4 / MOV / WebM を指定し、URL や CDN を書かない。該当するマテリアル名がモデル内にない場合は警告して無視される。
+- `materialOverrides` は `{ "<material 名>": { "texture": "<画像または動画の相対パス>" } }` の形で、名前が一致するマテリアルの `emissiveMap` を差し替える。**貼り先の材質が発光しない（glTF の `emissiveFactor` が未設定 = 黒）と、`materialOverrides` 単独では「0 × テクスチャ」で何も出ない**（2026-08-14 実害。詳細は後述「発光しない材質の emissiveMap」）。edit.json のあるディレクトリからの相対 PNG / JPEG / WebP 等、または MP4 / MOV / WebM を指定し、URL や CDN を書かない。該当するマテリアル名がモデル内にない場合は警告して無視される。
   - `textureVar` は画面に映すものをツマミ（CSS カスタムプロパティ）にする任意キー。`"--screen-src"` のような変数名を書き、overlay の `vars` でその変数に相対パスを入れると `texture` の代わりに差し込まれる。空・未設定なら `texture` がそのまま使われる。
   - `textureVar` を使う場合も `texture` は実在する相対パスのままにする。書き出し前の宣言済み入力検査が実ファイルを要求するため、`texture` に `var(--screen-src)` を直接書く形はライブプレビューでは動くが書き出しでは失敗する。
   - `brightness` は任意の発光倍率（0〜4、既定 1）で、差し替えたテクスチャの `emissiveIntensity` に掛かる。`var(--screen-brightness)` のような CSS 変数も書き出しを含めて使える。既定の 1 のときは `emissiveIntensity` に触れず、既存宣言の見た目を維持する。
@@ -448,7 +448,51 @@ texts[] anim と同じ「render は localSeconds の純関数」原則をその
 （人物セグメンテーション → 輪郭抽出 → 簡略化の自動生成は将来スキル化予定。現時点では手動）。
 被写体の直上を狙うだけなら `spawn` の矩形を人物の頭・肩幅に合わせて宣言すればよい。
 
-## 標準ツマミ（camera 投影 — pan / zoom。2026-08-06 導入）
+## 標準ツマミ（camera 投影と材質 finish）
+
+### 材質 finish の選択
+
+`finishes` は glb 内の `material.name` ごとに色と表面係数を宣言し、CSS カスタムプロパティ
+1 個で選択する。`var` の省略値は `--akari-3d-finish`。`default` は `options` 内に必須。
+選択名は英字または `_` で始まり、以降は英数字・`_`・`-` のみを使う。
+
+```json
+"finishes": {
+  "var": "--akari-3d-finish",
+  "default": "natural-titanium",
+  "options": {
+    "natural-titanium": { "FrameMat": { "color": "#c5c2b9", "metalness": 1, "roughness": 0.35 } },
+    "cosmic-orange": { "FrameMat": { "color": "#d66b33", "metalness": 1, "roughness": 0.4 } }
+  }
+}
+```
+
+各材質に指定できるキーは `color` / `metalness` / `roughness` / `clearcoat` /
+`clearcoatRoughness` / `emissive`。色は `#rrggbb` の 6 桁 hex、数値は 0〜1。
+モデルにない材質名や材質にないプロパティは警告して無視する。選択を変えるたび、各材質を
+`materialOverrides` 適用後の値へ戻してから指定キーだけ上書きするため、前の選択の値は残らない。
+テクスチャには一切触れない。
+
+```css
+.phone-live { --akari-3d-finish: var(--phone-finish, natural-titanium); }
+```
+
+素材 `meta.json` の knob は、既存の `cssVar` バインド形式で指定する:
+取りうる値は `finishes.options` のキーと一致させる。meta 側は `options` 配列を持たず、`label` に列挙する。
+
+```json
+{ "cssVar": "--phone-finish", "type": "dropdown", "group": "style", "label": "本体の仕上げ（natural-titanium / cosmic-orange）", "default": "natural-titanium" }
+```
+
+CSS 値が空なら `default`、未知の値なら警告を 1 回出して `default` を使う。
+`materialOverrides` は `emissiveMap` と `emissiveIntensity`（brightness）を扱い、
+`finishes` は `color` / `metalness` / `roughness` / `clearcoat` / `clearcoatRoughness` と
+`emissive` 色を扱う。`materialOverrides` を先に適用し、その結果を素の値として記録してから
+`finishes` が指定キーだけ上書きする。`emissiveMap` と `emissiveIntensity` は保持される。
+非発光の材質に貼った `emissiveMap` も、`finishes` で `emissive` を白などにすれば表示できる。
+ライブプレビューと書き出しは同じ経路で適用する。
+
+### カメラ投影の pan / zoom
 
 ランタイムは `--akari-3d-pan-x` / `--akari-3d-pan-y` / `--akari-3d-zoom` という 3 つの
 **標準カスタムプロパティ**を解釈する。断片ルート（または祖先）へ CSS で宣言すると、
@@ -601,11 +645,11 @@ container を渡しても、断片の外側からは同じ値が同じ式で読
 - 同梱クリップの尺・向きが用途に合わないことは珍しくない。合わないなら**作り直す方が速い**
   （§glb を直接編集する）
 
-### 発光しない材質には貼れない（materialOverrides の実測 2026-08-14）
+### 発光しない材質の emissiveMap（materialOverrides の実測 2026-08-14）
 
 `materialOverrides` の差し替え先は `emissiveMap` 固定である。three は `emissive`（glTF の
 `emissiveFactor`）を掛けてから合成するので、**`emissiveFactor` が未設定＝黒の材質へ貼っても
-「0 × テクスチャ」で完全に消える**。しかもエラーにならないため、原因に辿り着きにくい。
+`materialOverrides` 単独では「0 × テクスチャ」で完全に消える**。しかもエラーにならないため、原因に辿り着きにくい。
 
 実害: アプリアイコンの glb は前面（`IconFaceMaterial`）が非発光で、`materialOverrides` を
 宣言しても**白い樹脂の面のまま**だった。同じ宣言でスマホの画面（`ScreenMaterial` =
@@ -618,6 +662,8 @@ container を渡しても、断片の外側からは同じ値が同じ式で読
 - 対処 1（推奨）: モデル側の当該材質に `emissiveFactor: [1,1,1]` を与える。あわせて
   `baseColorFactor` を暗く落とすと、貼った絵の発色を下地が濁さない
 - 対処 2: 発光する材質（画面用など）を対象にする
+- 対処 3: `finishes` の同じ材質名に `"emissive": "#ffffff"` などを指定する。
+  `materialOverrides` の `emissiveMap` と `emissiveIntensity` は保持される
 - ランタイムは非発光の材質を対象にすると**警告を出す**（2026-08-14 追加）。ログを見ること
 
 ### 動きプリセットは「正面を向く時間」を実測してから使う（2026-08-14）