webtalekit-alpha 0.2.11 → 0.2.14

package/README.md

@@ -1,50 +1,84 @@
 # webTaleKit
 
-![wabTaleKitロゴ](s-plan1-5Light-s-1.jpg)
+![webTaleKitロゴ](s-plan1-5Light-s-1.jpg)
+
+**[English](README_EN.md) | 日本語**
 
 ## 目次
 
-- 概要
-- デモ
-- 環境構築手順
-- 動作確認手順
-- Quick Start（デモゲームを弄ってみよう）
-- できること
-- できないこと
-- フィードバックフォームのご案内
+- [概要](#概要)
+- [デモ](#デモ)
+- [ドキュメント](#ドキュメント)
+- [環境構築手順](#環境構築手順)
+- [動作確認手順](#動作確認手順)
+- [Quick Start(デモゲームを弄ってみよう)](#quick-startデモゲームを弄ってみよう)
+- [開発コマンド](#開発コマンド)
+- [シナリオ検証API](#シナリオ検証api)
+- [現在の状況](#現在の状況)
+- [ロードマップ](#ロードマップ実装予定)
+- [できること](#アルファ版01x-02xでできること)
+- [制限事項](#アルファ版01x-02xの制限事項)
 
 ## 概要
 
-TypeScript(JavaScript) ベースのビジュアルノベルゲームエンジンです。  
-UIをHTML・CSS・JavaScriptで柔軟に作成でき、シナリオをマークアップ言語とJavaScriptで制御できます。  
-自動スケーリング機能で、様々なウインドウで遊ぶことができます。  
-VS Codeの拡張機能を用いたGUIエディタやREST API呼び出しによる生成AI連携の追加を提供予定です。  
+TypeScript(JavaScript) ベースのビジュアルノベルゲームエンジンです。
+UIをHTML・CSS・JavaScriptで柔軟に作成でき、シナリオをマークアップ言語とJavaScriptで制御できます。
+自動スケーリング機能で、様々なウィンドウサイズに対応します。
+VS Codeの拡張機能を用いたGUIエディタやREST API呼び出しによる生成AI連携の追加を提供予定です。
+
+### 特徴
+
+- 🎮 **柔軟なUI作成**: HTML・CSS・JavaScriptで自由にUIをデザイン
+- 📝 **直感的なシナリオ記述**: マークアップ言語とJavaScriptでシナリオを制御
+- 🔄 **自動スケーリング**: 様々なウィンドウサイズに自動対応
+- 🎨 **豊富な画像処理**: フィルター・アニメーション機能を搭載
+- 🔊 **サウンド対応**: BGM・SE・ボイス再生に対応
+- 🛠️ **TypeScript対応**: TypeScriptでの開発をサポート
+- 🤖 **AI連携**: REST API呼び出しによる生成AI連携（予定）
 
 ## デモ
 
-Firefoxでも、Chromeでも、Edgeでも、好きなブラウザを使いたまえ・・・！
+Firefoxでも、Chromeでも、Edgeでも、好きなブラウザを使いたまえ・・・!
 <https://test-game-chi.vercel.app/>
-![alt text](image.png)
+![デモゲーム画面](image.png)
+
+## ドキュメント
+
+📖 **オンラインドキュメント**: <https://endohizumi.github.io/webTaleKit/>
 
 ## 環境構築手順
 
-1. Node.js(20以降)が必要です。(nvm等お好みの方法がある場合は、そちらでも構いません)
+1. Git が必要です。
+   - **インストール確認:** `git --version` でバージョンが表示されれば OK
+   - Windowsの場合は、Git公式サイト (<https://git-scm.com/>) からインストールしてください。
+   - Macの場合は、`brew install git` を実行してインストールしてください。
+   - Linuxの場合は、以下のコマンドを実行してインストールしてください。
+
+    ```bash
+    sudo apt-get update
+    sudo apt-get install git
+    ```
+
+2. Node.js(20以降)が必要です。(nvm等お好みの方法がある場合は、そちらでも構いません)
+   - **インストール確認:** `node --version` でv20以上のバージョンが表示されれば OK
    - Windowsの場合は、Node.js公式サイト (<https://nodejs.org/>) からインストールしてください。
    - Macの場合は、`brew install node` を実行してインストールしてください。
    - Linuxの場合は、以下のコマンドを実行して、インストールしてください。
 
     ```bash
-        curl -fsSL https://deb.nodesource.com/setup_lts.x | sudo -E bash -
-        sudo apt-get install -y nodejs
+    curl -fsSL https://deb.nodesource.com/setup_lts.x | sudo -E bash -
+    sudo apt-get install -y nodejs
     ```
 
-2. 以下のコマンドを実行してください
+3. 以下のコマンドを実行してください
 
     ``` bash
     npm create tale-game your-game-title
+    cd your-game-title
+    npm run play
     ```
 
-プロジェクトに移動して、`npm run play`を実行して、デモゲームが起動すれば、構築は完了です。
+デモゲームが起動すれば、構築は完了です。
 
 ## 動作確認手順
 
@@ -52,82 +86,172 @@ Firefoxでも、Chromeでも、Edgeでも、好きなブラウザを使いたま
 
 ```bash
 git clone https://github.com/EndoHizumi/testGame.git
+cd testGame
 npm install
 npm run play
 ```
 
-## Quick Start（デモゲームを弄ってみよう
-
-### 画像を差し替える
-
-- キャラを変える場合
-  - src/resource/chara/guide.png に上書きしてください。
-- 背景画像を変える
-  - src/resource/background/title_bg.png　に上書きしてください。
-- BGMを変える
-  - src/resource/bgm/title_theme.mp3　に上書きしてください。
-
-- 選択肢の画像を変える
-  - src\resource\system\systemPicture\02_button\button.png　に上書きしてください。
-- 選択肢(マウスオーバー時)の画像を変える
-  - src\resource\system\systemPicture\02_button\button2.png　に上書きしてください。
-- 選択肢(クリック時)の画像を変える
-  - src\resource\system\systemPicture\02_button\button3.png　に上書きしてください。
-
-- キャラを増やす
-  - src\resource\character 以下に表示したい画像を置きます。
-  - 登場させたい行数で、`<show src="表示したい画像のパス"></show>` を記述する
-- セリフを増やす
-  - セリフを表示させたい行数で、`<say name="キャラの名前">セリフをここに入れる</say>` を記述する
-- 地の文を増やす
-  - 地の文を表示させたい行数で、`<text>セリフをここに入れる</text>` を記述する
-
-- 選択肢を増やす
-  - 43行目のchoiceタグの中(44行-50行)で、以下のように記述すると、選択されたときに、地の文を表示する
-
-   ``` html
-    <item label='選択肢の文言'>
-        <text>セリフをここに入れる</text>
-    </item>
-   ```
-
-   実装例
-
-   ```　html
-          <choice prompt="ゲームを始めますか？">
-            <item label="はい">
-                <jump index="5" />
-            </item>
-            <item label="いいえ">
-                <jump index="16" />
-            </item>
-            <item label='ちょっと待ってくれ'>
-              <text>承知しました。</text>
-               <jump index="1" />
-            </item>
-        </choice>
-   ```
+## Quick Start(デモゲームを弄ってみよう)
+
+このセクションでは、プログラミングの知識がなくても簡単にゲームをカスタマイズできる方法を説明します。
+
+### 画像を差し替える(簡単なカスタマイズ)
+
+**手順:** 既存の画像ファイルを新しい画像で置き換える(ファイル名は同じにしてください)
+
+#### キャラクターや背景を変える
+
+- **キャラを変える場合**
+  - `./src/resource/chara/guide.png` を新しいキャラ画像で上書きしてください(ファイル名は `guide.png` のまま)
+- **背景画像を変える**
+  - `./src/resource/background/title_bg.png` を新しい背景画像で上書きしてください(ファイル名は `title_bg.png` のまま)
+- **BGMを変える**
+  - `./src/resource/bgm/title_theme.mp3` を新しい音楽ファイルで上書きしてください(ファイル名は `title_theme.mp3` のまま)
+
+#### ボタンの見た目を変える
+
+- **選択肢の画像を変える**
+  - `./src/resource/system/systemPicture/02_button/button.png`(通常時) - ファイル名は `button.png` のまま上書き
+  - `./src/resource/system/systemPicture/02_button/button2.png`(マウスを乗せた時) - ファイル名は `button2.png` のまま上書き
+  - `./src/resource/system/systemPicture/02_button/button3.png`(クリック時) - ファイル名は `button3.png` のまま上書き
+
+**パス表記について:**
+
+- `./` は「現在のプロジェクトフォルダから」という意味です
+- パス区切り文字は `/` (スラッシュ) を使用しています
+- **Windowsをお使いの方:** `\` (バックスラッシュ) でも動作しますが、上記の `/` 形式を推奨します
+
+### シナリオファイルを編集する(テキストの変更)
+
+シナリオファイル(`.scene`ファイル)をテキストエディタで開いて、以下の方法で内容を変更できます:
+
+#### 基本的な要素の追加
+
+- **キャラを増やす**
+  1. `./src/resource/character` フォルダに新しいキャラ画像を保存
+  2. シナリオファイルで `<show src="キャラ画像のファイル名"></show>` を記述
+- **セリフを増やす**
+  - `<say name="キャラの名前">ここにセリフを入力</say>` を記述
+- **地の文(ナレーション)を増やす**
+  - `<text>ここに地の文を入力</text>` を記述
+
+**初心者の方へ:** まずは既存のテキストを変更することから始めることをお勧めします。
+
+#### 選択肢を追加・変更する
+
+選択肢はプレイヤーがゲームの進行を選ぶ重要な要素です。シナリオファイル内の `<choice>` タグを編集することで変更できます。
+
+**基本的な選択肢の書き方:**
+
+``` html
+<item label='選択肢の文言'>
+    <text>選択後に表示される文章</text>
+</item>
+```
+
+**実用的な例:**
+
+```html
+<choice prompt="ゲームを始めますか?">
+  <item label="はい">
+      <jump index="5" />
+  </item>
+  <item label="いいえ">
+      <jump index="16" />
+  </item>
+  <item label='ちょっと待ってくれ'>
+    <text>承知しました。</text>
+     <jump index="1" />
+  </item>
+</choice>
+```
+
+## 開発コマンド
+
+### ビルドと開発
+
+- `npm run build` - TypeScriptをJavaScriptにコンパイルし、配布ファイルを準備
+- `npm run dev` - プロジェクトをビルドし、exampleフォルダで開発サーバーを起動
+- `npm run lint` - ESLintでコード品質をチェック
+- `npm run test` - Jestでテストを実行
+
+### CLIツール
+
+- `wtc` - WebTaleScriptパーサーCLI (`parser/cli.js` から利用可能)
+- 使用方法: `wtc <scene-file> [output-directory]` で `.scene` ファイルを `.js/.ts` ファイルに変換
+
+### ドキュメント
+
+- `npm run docs:dev` - VitePressドキュメントサーバーを起動
+- `npm run docs:build` - ドキュメントをビルド
+- `npm run docs:preview` - ビルドしたドキュメントをプレビュー
+
+## シナリオ検証API
+
+WebTaleKit には、シナリオ配列を検証しつつ、HTML風の文字列を非破壊でサニタイズできる公開APIがあります。
+
+- `validateScenarioObjects` - 検証結果とサニタイズ済みシナリオを返します
+- `formatValidationOutput` - エラーと警告を表示用文字列へ整形します
+- `createScenarioValidationError` - 検証結果から Error を生成します
+- `assertScenarioValidation` - エラーがある場合に例外を送出します
+- `reportScenarioValidation` - logger 経由で警告とエラーを出力します
+
+これらのAPIは、エンジン実行時に自動で強制適用されません。シナリオの読み込み時、エディタ連携時、独自ビルド処理時などに、利用者が必要に応じて呼び出す想定です。
+
+```ts
+import {
+  assertScenarioValidation,
+  reportScenarioValidation,
+  validateScenarioObjects,
+} from './src/utils/validateScenario'
+
+const result = validateScenarioObjects(scenarioObjects, commandList)
+
+await reportScenarioValidation(result, 'Scene import')
+assertScenarioValidation(result, 'Scene import')
+
+const safeScenario = result.sanitizedScenario
+```
+
+`sanitizedScenario` は元の入力配列を破壊せずに返されます。`sanitized` が `true` の場合は、HTML風の文字列がエスケープされています。
 
 ## 現在の状況
 
-webTaleKitは、現在アルファ版です。  
+webTaleKitは、現在アルファ版です。
 
 開発進捗は、[@endo_hizumi](https://x.com/endo_hizumi) で行っております。
 実装予定の項目については、こちらの[Trello](https://trello.com/b/qYNGh7MY)からも確認できます。
 
-デモをプレイした感想・WebTaleKitを使って気になったことなど、意見・感想はこちらで受け付けています！
+デモをプレイした感想・WebTaleKitを使って気になったことなど、意見・感想はこちらで受け付けています!
 [https://forms.gle/uejQwvwAb99wcJht7](https://forms.gle/uejQwvwAb99wcJht7)
 
 検索Hashtag: #webTalekit
 
+## ロードマップ(実装予定)
+
+| バージョン | コードネーム | codeName | 内容
+| :--- | :--- | :--- | :---
+| 0.1.0 | 初音| HATUNE | 初期リリース
+| 0.2.0 | 礎 | ISHIZUE | 基本機能アップデート<br>0.2.12〜<br>ダイアログ表示タグの追加<br>engineConfig反映バグの修正<br>未定義タグがある場合、undefineを呼び出すバグの修正<br>文字列以外を囲むとこける問題の修正<br>リンク切れでこける問題の修正<br>メッセージウィンドウオーバーフローの修正<br>if属性の実装<br>for属性の実装<br>既読管理の追加
+| 0.3.0 | 舞踊 | BUYO | トランジション・アニメーション関連のアップデート<br>テキストスピードの調整タグの追加<br>テキスト表示フォントサイズの変更<br>Webフォントのサポート(フォント変更設定の追加)<br>動画再生のサポート<br>子要素でフィルター・アニメーション設定
+| 0.4.0 | 狭間 | HAZAMA | Vue.jsやReact、SvelteなどのUIフレームワークとの連携追加のアップデート
+| 0.5.0 | 操手 | AYATURI |  ゲームパッドのサポート追加<br>キーコンフィグの追加<br>VOICEBOX APIの対応<br>npm run recの追加
+| 0.6.0 | 絡繰 | KARAKURI | wtsLinterの追加<br>VSCodeとの連携追加<br>wst2htmlの追加<br>プラグイン機能の追加<br>クロスプラットホームへのビルド追加
+| 0.7.0 | 綴り | TUDURI |  GUIエディタの追加
+| 0.8.0 | 迅雷 | JINRAI |  パフォーマンスアップデート
+| 0.9.0 | 出島 | DEJIMA |  KAGタグコンバータの追加
+| 1.0.0 | 暁月 | AKATUKI |  メジャーアップデート
+
 ## アルファ版(0.1.x-0.2.x)で、できること
 
 ### テキスト表示
+
 - 地の文の表示
 - キャラクターのセリフの表示・ボイスの再生
 - 定義した変数の表示
 
 ### キャラクター・画像操作
+
 - キャラクターの画像の表示・位置変更・アニメーション
 - その他の画像の画像の表示・位置変更・アニメーション
 - キャラクターの複数表示・位置変更・アニメーション
@@ -135,6 +259,7 @@ webTaleKitは、現在アルファ版です。
 - 背景画像の表示・変更
 
 ### 画像処理
+
 - 画像のフィルター操作
   - モノクロ化
   - セピア化
@@ -142,6 +267,7 @@ webTaleKitは、現在アルファ版です。
   - サイズの変更
 
 ### ユーザーインタラクション
+
 - 選択肢の表示
 - 選択肢の画像の変更
   - 通常時
@@ -151,53 +277,64 @@ webTaleKitは、現在アルファ版です。
 - Enterキーで全文表示
 
 ### シナリオ制御
+
 - 表示する文章・画像の条件分岐
 - セリフのジャンプ
-- シナリオ（シーン）の切り替え
+- シナリオ(シーン)の切り替え
 
 ### 音声
+
 - BGMの再生・停止
 - SEの再生・停止
 
+### セーブ&ロード
+
+- セーブ機能
+- ロード機能
+
 ### システム設定・UI
+
 - HTMLで作った画面の表示
 - 解像度の設定変更
 
 ### プログラミング連携
+
 - JavaScript連携
   - メソッドの呼び出し
   - 式の実行
   - 変数の定義・値の変更
 - JavaScript側での背景画像の変更
 - TypeScript連携
-- REST API呼び出し（レスポンスの表示）
+- REST API呼び出し(レスポンスの表示)
 
-## アルファ版（0.1.x-0.2.x）の制限事項
+## アルファ版(0.1.x-0.2.x)の制限事項
 
 ### ビルド・プラットフォーム
+
 - Desktopアプリケーションへのビルド
 - Android(iOS)向けのビルド
 
 ### ユーザーインターフェース (UI)
+
 - 画面各種のボタン
 - セーブファイルの一覧の取得
 
 ### キャラクター操作
+
 - sayタグの以下の機能
   - キャラが表示されていないときは、表示する
 
-### セーブ＆ロード
-- セーブ＆ロード機能
-
 ### 視覚効果
+
 - showタグ / hideタグの以下の機能
   - 子要素でフィルター指定
   - 子要素でアニメーション指定
   - スラッシュで区切ってリソース種類を指定
-- quakeタグ（画面を揺らす）
-- maskタグ（画面の暗転）
+- quakeタグ(画面を揺らす)
+- maskタグ(画面の暗転)
 
 ### 音声
+
 - soundタグの以下の機能
   - pause
   - setVolume
@@ -207,19 +344,26 @@ webTaleKitは、現在アルファ版です。
   - seエイリアス
 
 ### リソース管理
-- JavaScript側での背景画像の変更
+
 - JavaScriptでのリソースの動的定義
 
 ### 設定・最適化
+
 - ゲーム設定ファイルの反映
 - 画面用HTMLのcss・jsのインライン化・minify化
 
-## アイコン素材
+## ライセンス
+
+MIT License
+
+## クレジット
+
+### アイコン素材
 
 - <https://www.silhouette-illust.com/>
 
-## カラーコード
+### カラーコード
 
-青: #3178C6 (TypeScript BLue)
-緑: #02a889 (WebTaleKit Green)
-白: #f8f8f8 (White Smoke)
+- 青: #3178C6 (TypeScript Blue)
+- 緑: #02a889 (WebTaleKit Green)
+- 白: #f8f8f8 (White Smoke)

package/package.json

@@ -1,12 +1,18 @@
 {
   "name": "webtalekit-alpha",
-  "version": "0.2.11",
+  "version": "0.2.14",
   "description": "Web知識でノベルゲーを作ることを目指したやつ",
   "main": "./src/index.js",
   "scripts": {
     "lint": "eslint . --ext .ts --ext .js",
     "test": "jest",
-    "build": "rimraf ./dist/ && tsc && cp -r package.json README.md engineConfig.json parser/ dist/ && cp src/core/index.js  dist/src/core/"
+    "setup": "npm install && cd example && npm install",
+    "dev": "npm run build && cd example && npm run dev",
+    "api": "node server/api.js",
+    "build": "rimraf ./dist/ && tsc && cp -r package.json README.md engineConfig.json parser/ dist/ && cp src/core/index.js  dist/src/core/",
+    "docs:dev": "vitepress dev docs",
+    "docs:build": "vitepress build docs",
+    "docs:preview": "vitepress preview docs"
   },
   "bin": {
     "wtc": "parser/cli.js"
@@ -14,6 +20,9 @@
   "author": "EndoHizumi",
   "license": "MIT",
   "dependencies": {
+    "express": "^5.2.1",
+    "gsap": "^3.14.2",
+    "html-inline": "^1.2.0",
     "html-minifier": "^4.0.0",
     "html-to-json-parser": "^2.0.1",
     "rimraf": "^6.0.1",
@@ -42,6 +51,7 @@
     "ts-loader": "^9.5.1",
     "ts-node": "^10.9.2",
     "typescript": "^5.4.2",
+    "vitepress": "^1.6.4",
     "webpack": "^5.90.3",
     "webpack-cli": "^5.1.4",
     "webpack-dev-server": "^5.0.2"

package/parser/checker.js

@@ -0,0 +1,184 @@
+'use strict'
+
+/**
+ * トップレベルコマンドの一覧 (core/index.js の Core.commandList から抽出)。
+ * HTTP サブタグはこれらのコマンドいずれかの子要素として使用できる。
+ */
+const TOP_LEVEL_COMMANDS = [
+  'text', 'choice', 'show', 'newpage', 'hide', 'jump', 'sound', 'say',
+  'if', 'call', 'moveto', 'route', 'wait', 'dialog', 'save', 'load',
+]
+
+/**
+ * 各ノードタイプが配置できる親タイプを定義する。
+ * キー: 子ノードタイプ、値: 許可された親タイプの配列
+ */
+const ALLOWED_PARENTS = {
+  // choice 構造
+  item: ['choice'],
+  // dialog 構造
+  prompt: ['dialog'],
+  actions: ['dialog'],
+  action: ['actions'],
+  // if 構造
+  else: ['if'],
+  // then は <if> の子要素としても、トップレベルコマンドの HTTP レスポンスの子要素としても使用できる
+  then: ['if', ...TOP_LEVEL_COMMANDS],
+  // インラインテキスト装飾タグ (drawer.ts の createDecoratedElement と textHandler から)
+  color: ['text', 'say'],
+  ruby: ['text', 'say'],
+  b: ['text', 'say'],
+  i: ['text', 'say'],
+  br: ['text', 'say'],
+  // HTTP サブタグ (httpHandler から) — トップレベルコマンドの子要素として有効
+  header: TOP_LEVEL_COMMANDS,
+  data: TOP_LEVEL_COMMANDS,
+  error: TOP_LEVEL_COMMANDS,
+  progress: TOP_LEVEL_COMMANDS,
+}
+
+/**
+ * すべてのノードタイプに共通して有効な属性。
+ * - type: タグタイプ自体
+ * - content: 子ノードの配列
+ * - if: 条件付き実行 (core/index.js の runScenario)
+ * - get/post/put/delete: HTTP メソッド属性 (core/index.js の httpHandler)
+ */
+const GLOBAL_ATTRIBUTES = new Set(['type', 'content', 'if', 'get', 'post', 'put', 'delete'])
+
+/**
+ * ノードタイプごとの既知の属性セット (GLOBAL_ATTRIBUTES を除く)。
+ * このセットに含まれない属性は unknown_attribute 警告を生成する。
+ * このマップにないノードタイプは属性チェックをスキップする
+ * (<header> や <data> の子要素のような自由形式の子要素に対応)。
+ */
+const KNOWN_ATTRIBUTES = {
+  // トップレベルコマンド (core/index.js のハンドラ実装から取得)
+  text:     new Set(['name', 'speed', 'time']),
+  say:      new Set(['name', 'speed', 'voice']),
+  choice:   new Set(['prompt', 'position']),
+  show:     new Set(['src', 'name', 'mode', 'x', 'y', 'width', 'height', 'pos', 'look', 'entry', 'sepia', 'mono', 'blur', 'opacity', 'transition', 'duration']),
+  hide:     new Set(['name', 'mode', 'transition', 'duration']),
+  moveto:   new Set(['name', 'x', 'y', 'duration']),
+  sound:    new Set(['src', 'name', 'mode', 'play', 'loop', 'stop', 'pause']),
+  jump:     new Set(['index', 'sub']),
+  if:       new Set(['condition']),
+  call:     new Set(['method']),
+  route:    new Set(['to']),
+  wait:     new Set(['wait', 'time']),
+  newpage:  new Set([]),
+  dialog:   new Set(['name', 'template']),
+  save:     new Set(['slot', 'name', 'message']),
+  load:     new Set(['slot', 'message']),
+  // サブノード
+  item:     new Set(['label', 'id', 'default', 'hover', 'select', 'color', 'position']),
+  action:   new Set(['id', 'label', 'value']),
+  then:     new Set([]),
+  else:     new Set([]),
+  prompt:   new Set([]),
+  actions:  new Set([]),
+  // インラインテキスト装飾 (drawer.ts の createDecoratedElement から)
+  color:    new Set(['value']),
+  ruby:     new Set(['text']),
+  b:        new Set([]),
+  i:        new Set([]),
+  br:       new Set([]),
+  // HTTP サブタグ (header/data の子要素は自由形式のキーを使用するため、チェックしない)
+  header:   new Set([]),
+  data:     new Set([]),
+  error:    new Set([]),
+  progress: new Set([]),
+}
+
+/**
+ * 親子関係が不正な場合のエラーメッセージを生成する。
+ * @param {string} nodeType - 誤った位置に配置されたノードのタイプ
+ * @param {string|null} parentType - 実際の親タイプ。ルートの場合は null
+ * @param {string[]} allowedParents - 許可された親タイプの配列
+ * @returns {string}
+ */
+const buildInvalidParentMessage = (nodeType, parentType, allowedParents) => {
+  const allowed = allowedParents.map((p) => `<${p}>`).join(' or ')
+  const actual = parentType ? `<${parentType}>` : 'scenario root'
+  return `<${nodeType}> must be inside ${allowed}, but found inside ${actual}`
+}
+
+/**
+ * 未知の属性 (エンジンに無視される属性) の警告メッセージを生成する。
+ * @param {string} nodeType
+ * @param {string} attrName
+ * @returns {string}
+ */
+const buildUnknownAttributeMessage = (nodeType, attrName) => {
+  return `<${nodeType}> has unknown attribute "${attrName}" which will be ignored`
+}
+
+/**
+ * エンジンで認識されない属性をノード単位でチェックする。
+ * 該当する属性ごとに unknown_attribute 警告を結果配列に追加する。
+ * @param {Object} node
+ * @param {Array} results - 結果オブジェクトを蓄積する配列
+ */
+const checkAttributes = (node, results) => {
+  const nodeType = node.type
+  if (!nodeType) return
+  const knownForType = KNOWN_ATTRIBUTES[nodeType]
+  if (knownForType === undefined) return // 未知のノードタイプはスキップ
+  for (const key of Object.keys(node)) {
+    if (GLOBAL_ATTRIBUTES.has(key)) continue
+    if (knownForType.has(key)) continue
+    results.push({
+      type: 'unknown_attribute',
+      node: nodeType,
+      attribute: key,
+      message: buildUnknownAttributeMessage(nodeType, key),
+    })
+  }
+}
+
+/**
+ * ノードの親子関係の違反と未知の属性を再帰的にチェックする。
+ * @param {Array} nodes - パース済みシナリオノードの配列
+ * @param {string|null} parentType - 親ノードのタイプ。ルートの場合は null
+ * @param {Array} results - 結果オブジェクトを蓄積する配列
+ */
+const checkNodes = (nodes, parentType, results) => {
+  if (!Array.isArray(nodes)) return
+  for (const node of nodes) {
+    if (typeof node !== 'object' || node === null) continue
+    const nodeType = node.type
+    if (!nodeType) continue
+
+    const allowedParents = ALLOWED_PARENTS[nodeType]
+    if (allowedParents && !allowedParents.includes(parentType)) {
+      results.push({
+        type: 'invalid_parent',
+        node: nodeType,
+        parent: parentType,
+        message: buildInvalidParentMessage(nodeType, parentType, allowedParents),
+      })
+    }
+
+    checkAttributes(node, results)
+
+    if (Array.isArray(node.content)) {
+      checkNodes(node.content, nodeType, results)
+    }
+  }
+}
+
+/**
+ * パース済みシナリオ配列の構文エラーと属性警告をチェックする。
+ * 結果オブジェクトの配列を返す:
+ *   - type 'invalid_parent': 構造エラー (不正な親子関係)
+ *   - type 'unknown_attribute': 警告 (エンジンが読み取らない属性)
+ * @param {Array} scenario - パース・フラット化されたシナリオ配列
+ * @returns {Array}
+ */
+const check = (scenario) => {
+  const results = []
+  checkNodes(scenario, null, results)
+  return results
+}
+
+module.exports = { check, ALLOWED_PARENTS, KNOWN_ATTRIBUTES, GLOBAL_ATTRIBUTES }