@luna-editor/engine 0.2.0 → 0.3.1

package/dist/components/TimeWaitIndicator.js

@@ -0,0 +1,17 @@
+"use client";
+import { useEffect } from "react";
+/**
+ * 時間待ちコンポーネント
+ * time_waitブロックで使用され、指定秒数経過後に自動で次に進む
+ * UIは表示せず、タイマー機能のみを提供
+ */
+export const TimeWaitIndicator = ({ duration, onComplete, }) => {
+    useEffect(() => {
+        const timeoutId = setTimeout(() => {
+            onComplete();
+        }, duration * 1000);
+        return () => clearTimeout(timeoutId);
+    }, [duration, onComplete]);
+    // UIは表示しない
+    return null;
+};

package/dist/contexts/AudioContext.d.ts

@@ -5,6 +5,7 @@ export interface AudioSettings {
     voiceVolume: number;
     effectVolume: number;
     textSoundVolume: number;
+    muteAudio: boolean;
 }
 export declare const AudioProvider: ({ children, settings, }: {
     children: ReactNode;

package/dist/contexts/AudioContext.js

@@ -6,6 +6,7 @@ const AudioContext = createContext({
     voiceVolume: 1.0,
     effectVolume: 1.0,
     textSoundVolume: 1.0,
+    muteAudio: false,
 });
 export const AudioProvider = ({ children, settings, }) => {
     return (_jsx(AudioContext.Provider, { value: settings, children: children }));

package/dist/contexts/DataContext.d.ts

@@ -1,6 +1,7 @@
 import { type ReactNode } from "react";
-import type { DataAPI, DataContext, PlayerSettingsData } from "../sdk";
+import type { DataAPI, DataContext, EmotionEffectState, PlayerSettingsData } from "../sdk";
 type SettingsUpdater = (settings: Partial<PlayerSettingsData>) => void;
+type EmotionEffectUpdater = (state: EmotionEffectState | null) => void;
 /**
  * データプロバイダー
  * プラグインがシナリオ情報にリアクティブにアクセスするためのProvider
@@ -17,6 +18,7 @@ type SettingsUpdater = (settings: Partial<PlayerSettingsData>) => void;
 export declare const DataProvider: React.FC<{
     data: DataContext;
     onSettingsUpdate?: SettingsUpdater;
+    onEmotionEffectUpdate?: EmotionEffectUpdater;
     children: ReactNode;
 }>;
 /**

package/dist/contexts/DataContext.js

@@ -1,8 +1,11 @@
 import { jsx as _jsx } from "react/jsx-runtime";
 import { createContext, useCallback, useContext, useEffect, useMemo, useRef, } from "react";
 const DataContextInstance = createContext(null);
+// データへの参照を共有するContext（Context value自体は変わらない）
+const DataRefContext = createContext(null);
 const SubscribersContext = createContext(null);
 const SettingsUpdaterContext = createContext(null);
+const EmotionEffectUpdaterContext = createContext(null);
 /**
  * データプロバイダー
  * プラグインがシナリオ情報にリアクティブにアクセスするためのProvider
@@ -16,10 +19,15 @@ const SettingsUpdaterContext = createContext(null);
  * </DataProvider>
  * ```
  */
-export const DataProvider = ({ data, onSettingsUpdate, children }) => {
-    const subscribers = useMemo(() => new Map(), // eslint-disable-line @typescript-eslint/no-explicit-any
-    []);
+export const DataProvider = ({ data, onSettingsUpdate, onEmotionEffectUpdate, children }) => {
+    const subscribers = useMemo(() => new Map(), []);
     const previousDataRef = useRef(data);
+    // 安定したデータ参照ホルダー（Context valueとして提供）
+    // オブジェクト自体の参照は変わらず、currentプロパティを更新
+    // これにより、useContextを使うコンポーネントは再レンダリングされない
+    const dataRefHolder = useMemo(() => ({ current: data }), [data]);
+    // dataが変わるたびにcurrentを更新
+    dataRefHolder.current = data;
     // データ変更時に購読者に通知
     useEffect(() => {
         const prevData = previousDataRef.current;
@@ -32,16 +40,20 @@ export const DataProvider = ({ data, onSettingsUpdate, children }) => {
             if (prevValue !== currentValue) {
                 // カテゴリ全体の購読者に通知
                 const categorySubscribers = subscribers.get(key);
-                categorySubscribers === null || categorySubscribers === void 0 ? void 0 : categorySubscribers.forEach((callback) => callback(currentValue));
+                categorySubscribers === null || categorySubscribers === void 0 ? void 0 : categorySubscribers.forEach((callback) => {
+                    callback(currentValue);
+                });
                 // 個別プロパティの変更をチェック
                 if (typeof currentValue === "object" && currentValue !== null) {
                     for (const prop of Object.keys(currentValue)) {
-                        const prevPropValue = prevValue === null || prevValue === void 0 ? void 0 : prevValue[prop]; // eslint-disable-line @typescript-eslint/no-explicit-any
-                        const currentPropValue = currentValue[prop]; // eslint-disable-line @typescript-eslint/no-explicit-any
+                        const prevPropValue = prevValue === null || prevValue === void 0 ? void 0 : prevValue[prop];
+                        const currentPropValue = currentValue[prop];
                         if (prevPropValue !== currentPropValue) {
                             const propKey = `${key}.${prop}`;
                             const propSubscribers = subscribers.get(propKey);
-                            propSubscribers === null || propSubscribers === void 0 ? void 0 : propSubscribers.forEach((callback) => callback(currentPropValue));
+                            propSubscribers === null || propSubscribers === void 0 ? void 0 : propSubscribers.forEach((callback) => {
+                                callback(currentPropValue);
+                            });
                         }
                     }
                 }
@@ -49,26 +61,38 @@ export const DataProvider = ({ data, onSettingsUpdate, children }) => {
         }
         previousDataRef.current = data;
     }, [data, subscribers]);
-    return (_jsx(SubscribersContext.Provider, { value: subscribers, children: _jsx(SettingsUpdaterContext.Provider, { value: onSettingsUpdate !== null && onSettingsUpdate !== void 0 ? onSettingsUpdate : null, children: _jsx(DataContextInstance.Provider, { value: data, children: children }) }) }));
+    return (_jsx(SubscribersContext.Provider, { value: subscribers, children: _jsx(SettingsUpdaterContext.Provider, { value: onSettingsUpdate !== null && onSettingsUpdate !== void 0 ? onSettingsUpdate : null, children: _jsx(EmotionEffectUpdaterContext.Provider, { value: onEmotionEffectUpdate !== null && onEmotionEffectUpdate !== void 0 ? onEmotionEffectUpdate : null, children: _jsx(DataRefContext.Provider, { value: dataRefHolder, children: _jsx(DataContextInstance.Provider, { value: data, children: children }) }) }) }) }));
 };
 /**
  * DataAPI実装を提供するフック
  * プラグインから呼び出される
  */
 export function useDataAPI() {
-    const data = useContext(DataContextInstance);
+    var _a;
+    // DataRefContextから安定したデータ参照を取得
+    // これはContext valueが変わらないので、再レンダリングを引き起こさない
+    const dataRefHolder = useContext(DataRefContext);
     const subscribers = useContext(SubscribersContext);
     const settingsUpdater = useContext(SettingsUpdaterContext);
-    if (!data || !subscribers) {
+    const emotionEffectUpdater = useContext(EmotionEffectUpdaterContext);
+    // 注意: usePlaybackTextOptional()をここで呼ぶと、PlaybackTextContextの更新で
+    // useDataAPIを使う全コンポーネントが再レンダリングされてしまう
+    // 代わりに、displayTextが必要なコンポーネントはusePlaybackText()を直接使う
+    if (!dataRefHolder || !subscribers) {
         throw new Error("useDataAPI must be used within DataProvider");
     }
     const get = useCallback((key, property) => {
-        var _a;
+        const currentData = dataRefHolder.current;
         if (property !== undefined) {
-            return (_a = data[key]) === null || _a === void 0 ? void 0 : _a[property];
+            const value = currentData[key];
+            if (value && typeof value === "object" && property in value) {
+                return value[property];
+            }
+            return undefined;
         }
-        return data[key];
-    }, [data]);
+        return currentData[key];
+    }, [dataRefHolder.current] // 依存配列を空にして、get関数を安定化
+    );
     const subscribe = useCallback((key, callback) => {
         var _a;
         const subscriberKey = key;
@@ -79,7 +103,8 @@ export function useDataAPI() {
         // unsubscribe関数を返す
         return () => {
             var _a;
-            (_a = subscribers.get(subscriberKey)) === null || _a === void 0 ? void 0 : _a.delete(callback);
+            (_a = subscribers
+                .get(subscriberKey)) === null || _a === void 0 ? void 0 : _a.delete(callback);
         };
     }, [subscribers]);
     const watch = useCallback((key, property, callback) => {
@@ -92,7 +117,8 @@ export function useDataAPI() {
         // unsubscribe関数を返す
         return () => {
             var _a;
-            (_a = subscribers.get(subscriberKey)) === null || _a === void 0 ? void 0 : _a.delete(callback);
+            (_a = subscribers
+                .get(subscriberKey)) === null || _a === void 0 ? void 0 : _a.delete(callback);
         };
     }, [subscribers]);
     const updateSettings = useCallback((settings) => {
@@ -103,10 +129,71 @@ export function useDataAPI() {
             console.warn("updateSettings called but no settings updater provided");
         }
     }, [settingsUpdater]);
+    const setBgmVolume = useCallback((volume) => {
+        const clampedVolume = Math.max(0, Math.min(1, volume));
+        updateSettings({ bgmVolume: clampedVolume });
+    }, [updateSettings]);
+    const setSeVolume = useCallback((volume) => {
+        const clampedVolume = Math.max(0, Math.min(1, volume));
+        updateSettings({ seVolume: clampedVolume });
+    }, [updateSettings]);
+    const setVoiceVolume = useCallback((volume) => {
+        const clampedVolume = Math.max(0, Math.min(1, volume));
+        updateSettings({ voiceVolume: clampedVolume });
+    }, [updateSettings]);
+    const setVolumes = useCallback((volumes) => {
+        const settings = {};
+        if (volumes.bgm !== undefined) {
+            settings.bgmVolume = Math.max(0, Math.min(1, volumes.bgm));
+        }
+        if (volumes.se !== undefined) {
+            settings.seVolume = Math.max(0, Math.min(1, volumes.se));
+        }
+        if (volumes.voice !== undefined) {
+            settings.voiceVolume = Math.max(0, Math.min(1, volumes.voice));
+        }
+        if (Object.keys(settings).length > 0) {
+            updateSettings(settings);
+        }
+    }, [updateSettings]);
+    const getBlockOption = useCallback((key) => {
+        var _a;
+        const currentBlock = (_a = dataRefHolder.current.playback) === null || _a === void 0 ? void 0 : _a.currentBlock;
+        if (!(currentBlock === null || currentBlock === void 0 ? void 0 : currentBlock.options)) {
+            return undefined;
+        }
+        return currentBlock.options[key];
+    }, [(_a = dataRefHolder.current.playback) === null || _a === void 0 ? void 0 : _a.currentBlock] // 依存配列を空にして安定化
+    );
+    const updateEmotionEffect = useCallback((state) => {
+        if (emotionEffectUpdater) {
+            emotionEffectUpdater(state);
+        }
+        else {
+            console.warn("updateEmotionEffect called but no emotion effect updater provided");
+        }
+    }, [emotionEffectUpdater]);
     return useMemo(() => ({
         get,
         subscribe,
         watch,
         updateSettings,
-    }), [get, subscribe, watch, updateSettings]);
+        setBgmVolume,
+        setSeVolume,
+        setVoiceVolume,
+        setVolumes,
+        getBlockOption,
+        updateEmotionEffect,
+    }), [
+        get,
+        subscribe,
+        watch,
+        updateSettings,
+        setBgmVolume,
+        setSeVolume,
+        setVoiceVolume,
+        setVolumes,
+        getBlockOption,
+        updateEmotionEffect,
+    ]);
 }

package/dist/contexts/PlaybackTextContext.d.ts

@@ -0,0 +1,32 @@
+import { type ReactNode } from "react";
+/**
+ * 文字送り用の軽量コンテキスト
+ * displayText と isTyping は頻繁に更新されるため、
+ * DataContext から分離して不要な再レンダリングを防ぐ
+ */
+interface PlaybackTextContextValue {
+    /** 現在表示中のテキスト（文字送り中は部分テキスト） */
+    displayText: string | React.ReactNode;
+    /** 文字送り中かどうか */
+    isTyping: boolean;
+}
+/**
+ * PlaybackTextProvider
+ * 文字送り状態を提供するProvider
+ * DataProviderとは別に、displayTextとisTypingのみを管理
+ */
+export declare const PlaybackTextProvider: React.FC<{
+    displayText: string | React.ReactNode;
+    isTyping: boolean;
+    children: ReactNode;
+}>;
+/**
+ * 文字送り状態を取得するフック
+ */
+export declare function usePlaybackText(): PlaybackTextContextValue;
+/**
+ * 文字送り状態を取得するフック（オプショナル版）
+ * PlaybackTextProviderの外でも使用可能（その場合はnullを返す）
+ */
+export declare function usePlaybackTextOptional(): PlaybackTextContextValue | null;
+export {};

package/dist/contexts/PlaybackTextContext.js

@@ -0,0 +1,29 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { createContext, useContext, useMemo } from "react";
+const PlaybackTextContextInstance = createContext(null);
+/**
+ * PlaybackTextProvider
+ * 文字送り状態を提供するProvider
+ * DataProviderとは別に、displayTextとisTypingのみを管理
+ */
+export const PlaybackTextProvider = ({ displayText, isTyping, children }) => {
+    const value = useMemo(() => ({ displayText, isTyping }), [displayText, isTyping]);
+    return (_jsx(PlaybackTextContextInstance.Provider, { value: value, children: children }));
+};
+/**
+ * 文字送り状態を取得するフック
+ */
+export function usePlaybackText() {
+    const context = useContext(PlaybackTextContextInstance);
+    if (!context) {
+        throw new Error("usePlaybackText must be used within PlaybackTextProvider");
+    }
+    return context;
+}
+/**
+ * 文字送り状態を取得するフック（オプショナル版）
+ * PlaybackTextProviderの外でも使用可能（その場合はnullを返す）
+ */
+export function usePlaybackTextOptional() {
+    return useContext(PlaybackTextContextInstance);
+}

package/dist/data-api-types.d.ts

@@ -0,0 +1,251 @@
+import type React from "react";
+import type { EmotionEffectState } from "./emotion-effect-types";
+import type { BackgroundData, BacklogEntry, BranchChoiceHistory, ConversationBranchState, DisplayedCharacter, ScenarioBlock, WorkFont } from "./types";
+/**
+ * シナリオ再生の動的データ
+ */
+export interface ScenarioPlaybackData {
+    /** 現在のブロックインデックス（0始まり） */
+    currentBlockIndex: number;
+    /** 総ブロック数 */
+    totalBlocks: number;
+    /** 現在のシナリオID */
+    scenarioId: string;
+    /** シナリオ名 */
+    scenarioName: string;
+    /** 現在のブロック */
+    currentBlock: ScenarioBlock | null;
+    /** 表示中のテキスト（改行は自動的に<br />に変換されます） */
+    displayText?: string | React.ReactNode;
+    /** テキストアニメーション中かどうか */
+    isTyping?: boolean;
+    /** 表示中のキャラクター */
+    displayedCharacters?: DisplayedCharacter[];
+}
+/**
+ * バックログデータ
+ */
+export interface BacklogData {
+    /** バックログエントリ */
+    entries: BacklogEntry[];
+    /** 総エントリ数 */
+    totalEntries: number;
+    /** ログエントリを追加 */
+    addLogEntry?: (entry: BacklogEntry) => void;
+    /** ログをクリア */
+    clearLogs?: () => void;
+}
+/**
+ * プレイヤー設定データ
+ */
+export interface PlayerSettingsData {
+    /** テキスト速度 (ミリ秒/文字) */
+    textSpeed: number;
+    /** 自動再生速度 (秒) */
+    autoPlaySpeed: number;
+    /** BGM音量 (0-1) */
+    bgmVolume: number;
+    /** SE音量 (0-1) */
+    seVolume: number;
+    /** ボイス音量 (0-1) */
+    voiceVolume: number;
+    /** スキップ設定 */
+    skipMode?: "all" | "unread" | "none";
+    /** 選択されたフォントファミリー（テキスト用） */
+    selectedFontFamily?: string;
+    /** 選択されたUIフォントファミリー（メニュー・ラベル等） */
+    selectedUIFontFamily?: string;
+}
+/**
+ * プラグインアセットデータ
+ */
+export interface PluginAssetsData {
+    /**
+     * プラグインのアセットURLを取得
+     * @param pluginName - プラグインのパッケージ名
+     * @param filename - アセットファイル名
+     * @returns アセットのURL
+     */
+    getAssetUrl: (pluginName: string, filename: string) => string;
+}
+/**
+ * フォントデータ
+ */
+export interface FontsData {
+    /** 利用可能なフォント一覧 */
+    fonts: WorkFont[];
+    /** 選択されているフォントファミリー（テキスト用） */
+    selectedFontFamily: string | undefined;
+    /** 選択されているUIフォントファミリー（メニュー・ラベル等） */
+    selectedUIFontFamily: string | undefined;
+    /** フォントが読み込み完了しているかどうか */
+    isLoaded: boolean;
+}
+/**
+ * 全データコンテキスト
+ *
+ * @remarks
+ * このインターフェースは、プラグインがDataAPI経由でアクセスできる全てのデータカテゴリを定義します。
+ * 各プロパティは、プラグインが特定のデータにアクセスする際のキーとして使用されます。
+ *
+ * @example
+ * ```typescript
+ * // 現在のブロックインデックスを取得
+ * const blockIndex = api.data.get('playback', 'currentBlockIndex');
+ *
+ * // 再生データ全体を購読
+ * api.data.subscribe('playback', (data) => {
+ *   console.log('Playback updated:', data);
+ * });
+ * ```
+ */
+export interface DataContext {
+    /** シナリオ再生情報 */
+    playback: ScenarioPlaybackData;
+    /** バックログ情報 */
+    backlog: BacklogData;
+    /** プレイヤー設定 */
+    settings: PlayerSettingsData;
+    /** プラグインアセット */
+    pluginAssets: PluginAssetsData;
+    /** 会話分岐データ */
+    branchData?: ConversationBranchState;
+    /** 分岐履歴 */
+    branchHistory?: BranchChoiceHistory[];
+    /** 現在の背景データ（単一、後方互換性用） */
+    background?: BackgroundData | null;
+    /** 現在の背景データ（複数、背景グループ対応） */
+    backgrounds?: BackgroundData[];
+    /** フォント設定 */
+    fonts?: FontsData;
+    /**
+     * 【機能概要】: 感情エフェクトの表示状態
+     * 【実装方針】: オプショナルプロパティとして追加し、後方互換性を保つ
+     * 【テスト対応】: TC-007, TC-014を通すための実装
+     * 🔵 信頼性レベル: 要件定義書（行101-111）とnote.md（行244-251）で明確に定義されている
+     *
+     * @see EmotionEffectState - 完全な型定義は emotion-effect-types.ts を参照
+     */
+    emotionEffect?: EmotionEffectState | null;
+}
+/**
+ * データ購読コールバック
+ *
+ * @typeParam T - 購読するデータの型
+ */
+export type DataSubscriber<T> = (data: T) => void;
+/**
+ * データAPI - プラグインからのデータアクセスインターフェース
+ *
+ * @remarks
+ * このAPIは、プラグインがシナリオエンジンの状態データにアクセスするための2つのアプローチを提供します：
+ * - Pull型: `get()` メソッドで現在の値を取得
+ * - Push型: `subscribe()` / `watch()` メソッドで変更を監視
+ *
+ * @example Pull型（現在値の取得）
+ * ```typescript
+ * const blockIndex = api.data.get('playback', 'currentBlockIndex');
+ * const playback = api.data.get('playback');
+ * ```
+ *
+ * @example Push型（変更の監視）
+ * ```typescript
+ * const unsubscribe = api.data.subscribe('playback', (data) => {
+ *   console.log('Playback updated:', data);
+ * });
+ * // cleanup
+ * unsubscribe();
+ * ```
+ *
+ * @example プロパティ単位での監視
+ * ```typescript
+ * api.data.watch('playback', 'currentBlockIndex', (index) => {
+ *   console.log('Block changed to:', index);
+ * });
+ * ```
+ */
+export interface DataAPI {
+    /**
+     * データの現在値を取得（Pull型）
+     * @param key - データカテゴリ
+     */
+    get<K extends keyof DataContext>(key: K): DataContext[K];
+    /**
+     * データの特定プロパティを取得（Pull型）
+     * @param key - データカテゴリ
+     * @param property - プロパティ名
+     */
+    get<K extends keyof DataContext, P extends keyof DataContext[K]>(key: K, property: P): DataContext[K][P];
+    /**
+     * データカテゴリ全体の変更を監視（Push型）
+     * @param key - データカテゴリ
+     * @param callback - 変更時のコールバック
+     * @returns unsubscribe関数
+     */
+    subscribe<K extends keyof DataContext>(key: K, callback: DataSubscriber<DataContext[K]>): () => void;
+    /**
+     * 特定プロパティの変更を監視（Push型）
+     * @param key - データカテゴリ
+     * @param property - プロパティ名
+     * @param callback - 変更時のコールバック
+     * @returns unsubscribe関数
+     */
+    watch<K extends keyof DataContext, P extends keyof DataContext[K]>(key: K, property: P, callback: DataSubscriber<DataContext[K][P]>): () => void;
+    /**
+     * プレイヤー設定を更新
+     * @param settings - 更新する設定値（部分更新可能）
+     */
+    updateSettings(settings: Partial<PlayerSettingsData>): void;
+    /**
+     * BGM音量を設定
+     * @param volume - 音量（0-1の範囲）
+     */
+    setBgmVolume(volume: number): void;
+    /**
+     * SE音量を設定
+     * @param volume - 音量（0-1の範囲）
+     */
+    setSeVolume(volume: number): void;
+    /**
+     * ボイス音量を設定
+     * @param volume - 音量（0-1の範囲）
+     */
+    setVoiceVolume(volume: number): void;
+    /**
+     * 全カテゴリの音量を一括設定
+     * @param volumes - カテゴリ別音量設定
+     */
+    setVolumes(volumes: {
+        bgm?: number;
+        se?: number;
+        voice?: number;
+    }): void;
+    /**
+     * 現在のブロックのオプション値を型安全に取得
+     *
+     * @example
+     * ```typescript
+     * // プラグイン側で型を定義
+     * type MyBlockOptions = {
+     *   ultemist_bubble_style: "normal" | "monologue" | "star";
+     *   ultemist_effect_type: "none" | "shake" | "fade";
+     * };
+     *
+     * // コンポーネントで使用
+     * const bubbleStyle = dataAPI.getBlockOption<MyBlockOptions, "ultemist_bubble_style">("ultemist_bubble_style");
+     * // 型: "normal" | "monologue" | "star" | undefined
+     *
+     * // または簡易版（キーのみ指定）
+     * const bubbleStyle = dataAPI.getBlockOption<MyBlockOptions>("ultemist_bubble_style");
+     * ```
+     *
+     * @param key - オプションのキー
+     * @returns オプションの値、または未設定の場合undefined
+     */
+    getBlockOption<T extends Record<string, unknown>, K extends keyof T = keyof T>(key: K): T[K] | undefined;
+    /**
+     * 感情エフェクトの状態を更新
+     * @param state - 更新する感情エフェクトの状態
+     */
+    updateEmotionEffect(state: EmotionEffectState | null): void;
+}

package/dist/data-api-types.js

@@ -0,0 +1,6 @@
+// ============================================================================
+// Data API Types - プラグインからのデータアクセス用型定義
+// ============================================================================
+// このファイルはDataAPIで使用される型定義を提供します
+// SDK全体のファイルサイズを管理するために分離されています
+export {};

package/dist/emotion-effect-types.d.ts

@@ -0,0 +1,86 @@
+/**
+ * 【機能概要】: 7種類の感情エフェクトタイプを定義
+ * 【実装方針】: 文字列リテラル型のユニオン型として定義し、型安全性を保証
+ * 【テスト対応】: TC-001, TC-010を通すための実装
+ * 🔵 信頼性レベル: 要件定義書（sdk-datacontext-extension-requirements.md行60-62）とnote.md（行201-210）で明確に定義されている
+ */
+export type EmotionType = "runrun" | "shonbori" | "kirakira" | "akire" | "heart" | "bikkuri" | "punpun";
+/**
+ * 【機能概要】: エフェクト配置の基準位置タイプを定義
+ * 【実装方針】: キャラクター全体または顔を基準とする2択を文字列リテラル型で表現
+ * 【テスト対応】: TC-002, TC-011を通すための実装
+ * 🔵 信頼性レベル: 要件定義書（行64-67）とnote.md（行212-214）で明確に定義されている
+ */
+export type PositionType = "character" | "face";
+/**
+ * 【機能概要】: エフェクトの相対位置を定義
+ * 【実装方針】: 7種類の位置指定を文字列リテラル型で表現
+ * 【テスト対応】: TC-003, TC-012を通すための実装
+ * 🔵 信頼性レベル: 要件定義書（行69-72）とnote.md（行216-224）で明確に定義されている
+ */
+export type EffectPosition = "above" | "below" | "left" | "right" | "center" | "top-left" | "bottom-left";
+/**
+ * 【機能概要】: キャラクターの顔位置情報を定義
+ * 【実装方針】: 顔の中心座標と幅・高さを表現するインターフェース
+ * 【テスト対応】: TC-004, TC-009, TC-020を通すための実装
+ * 🔵 信頼性レベル: 要件定義書（行82-88）、note.md（行234-243）、既存のCharacterSpeakContext定義（sdk.ts行552-558）に基づく
+ */
+export interface FacePosition {
+    /** 顔中心のX座標（キャラクター要素内の相対位置、単位: px） */
+    x: number;
+    /** 顔中心のY座標（キャラクター要素内の相対位置、単位: px） */
+    y: number;
+    /** 顔の幅（単位: px） */
+    width: number;
+    /** 顔の高さ（単位: px） */
+    height: number;
+}
+/**
+ * 【機能概要】: エフェクトの位置設定を統合的に管理
+ * 【実装方針】: 基準位置タイプ、相対位置、オフセット値を組み合わせた設定オブジェクト
+ * 【テスト対応】: TC-005, TC-015, TC-016, TC-017を通すための実装
+ * 🔵 信頼性レベル: 要件定義書（行74-80）とnote.md（行226-231）で明確に定義されている
+ */
+export interface EmotionEffectPosition {
+    /** 基準位置タイプ（キャラクター全体または顔） */
+    positionType: PositionType;
+    /** エフェクトの相対位置 */
+    position: EffectPosition;
+    /** X軸オフセット（-500〜500px、デフォルト0） */
+    offsetX: number;
+    /** Y軸オフセット（-500〜500px、デフォルト0） */
+    offsetY: number;
+}
+/**
+ * 【機能概要】: 感情エフェクトの表示状態を包括的に管理
+ * 【実装方針】: エフェクト表示に必要な全ての状態情報を集約したインターフェース
+ * 【テスト対応】: TC-006, TC-008, TC-009, TC-013, TC-018, TC-021, TC-022を通すための実装
+ * 🔵 信頼性レベル: 要件定義書（行88-97）とnote.md（行187-198）で明確に定義されている
+ *
+ * @remarks
+ * このインターフェースは、感情エフェクトの表示に必要な全ての状態を表現します。
+ * - speaker と facePosition はオプショナルで、プラグインがキャラクター情報を必要とする場合に使用します
+ * - targetCharacterId が null の場合、現在の発話キャラクターを対象とします
+ * - position には基準位置タイプと相対位置、オフセット値が含まれます
+ */
+export interface EmotionEffectState {
+    /** エフェクト表示が有効か（true: 表示、false: 非表示） */
+    enabled: boolean;
+    /** 感情タイプ（7種類のいずれか） */
+    emotionType: EmotionType;
+    /** 対象キャラクターID（nullは発話キャラクター） */
+    targetCharacterId: string | null;
+    /** エフェクト位置設定 */
+    position: EmotionEffectPosition;
+    /** 音声再生するか（true: 再生、false: 再生しない） */
+    playSound: boolean;
+    /** 発話キャラクター情報（オプショナル） */
+    speaker?: {
+        id: string;
+        name: string;
+        state?: string;
+        position?: number;
+    };
+    /** 顔位置情報（FacePosition型、オプショナル） */
+    facePosition?: FacePosition;
+}

package/dist/emotion-effect-types.js

@@ -0,0 +1,6 @@
+// ============================================================================
+// Emotion Effect Types - 感情エフェクト関連の型定義
+// ============================================================================
+// このファイルは感情エフェクトプラグインで使用される型定義を提供します
+// SDK全体のファイルサイズを管理するために分離されています
+export {};