npm - next2d-development-mcp - Versions diffs - 1.1.4 → 1.1.6 - Mend

next2d-development-mcp 1.1.4 → 1.1.6

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (4) hide show

package/dist/index.js +1 -1
package/dist/references/develop-specs.md +17 -3
package/dist/references/framework-specs.md +201 -68
package/package.json +11 -11

package/dist/index.js CHANGED Viewed

@@ -6,7 +6,7 @@ import { registerResources } from "./resources/index.js";
 import { registerPrompts } from "./prompts/index.js";
 const server = new McpServer({
     "name": "next2d-development-mcp",
-    "version": "0.0.2"
+    "version": "1.1.6"
 });
 registerTools(server);
 registerResources(server);

package/dist/references/develop-specs.md CHANGED Viewed

@@ -1626,12 +1626,26 @@ style-src 'self';
 ## Anti-Patterns
 ```typescript
-// NG: Viewでビジネスロジック
+// NG: Viewでビジネスロジック + addEventListener に async 関数を直接渡す
+// async () => {} を渡すと Promise が返り、@next2d/player がチャンネルを保持したまま
+// SPA 遷移で閉じられ "A listener indicated an asynchronous response by returning true,
+// but the message channel closed before a response was received" エラーが発生する。
 class BadView extends View {
     async initialize() {
         btn.addEventListener(PointerEvent.POINTER_DOWN, async () => {
-            const data = await Repository.get(); // NG
-            this.processData(data);              // NG
+            const data = await Repository.get(); // NG: ビジネスロジック in View
+            this.processData(data);              // NG: ビジネスロジック in View
+        });
+    }
+}
+// OK: 同期ハンドラ内で void IIFE を使い Promise を捨てる
+class GoodView extends View {
+    async initialize() {
+        btn.addEventListener(PointerEvent.POINTER_DOWN, () => {  // 同期関数
+            void (async () => {
+                await this.vm.onClickButton();  // OK: VMに委譲
+            })();
         });
     }
 }

package/dist/references/framework-specs.md CHANGED Viewed

@@ -513,9 +513,11 @@ src/config/
 └── routing.json   # ルーティング設定
 ```
+---
 ## stage.json
-表示領域（Stage）の設定を行うJSONファイルです。
+表示領域（Stage）の設定を行うJSONファイルです。アプリ起動時に一度だけ読み込まれ、Stageの初期パラメータとして使用されます。
 ```json
 {
@@ -534,22 +536,30 @@ src/config/
 | プロパティ | 型 | デフォルト | 説明 |
 |-----------|------|----------|------|
-| `width` | number | 240 | 表示領域の幅 |
-| `height` | number | 240 | 表示領域の高さ |
-| `fps` | number | 60 | 1秒間に何回描画するか（1〜60） |
-| `options` | object | null | オプション設定 |
+| `width` | number | 240 | 表示領域の幅（ピクセル単位）。実際の描画キャンバスの基準幅として使用される |
+| `height` | number | 240 | 表示領域の高さ（ピクセル単位）。実際の描画キャンバスの基準高さとして使用される |
+| `fps` | number | 60 | 1秒間の描画回数。指定可能な範囲は 1〜60 |
+| `options` | object | null | 追加オプション設定。省略可能 |
-### options設定
+### options 設定
 | プロパティ | 型 | デフォルト | 説明 |
 |-----------|------|----------|------|
-| `fullScreen` | boolean | false | Stageで設定した幅と高さを超えて画面全体に描画 |
-| `tagId` | string | null | IDを指定すると、指定したIDのエレメント内で描画を行う |
-| `bgColor` | string | "transparent" | 背景色を16進数で指定。デフォルトは無色透明 |
+| `fullScreen` | boolean | false | `true` にするとウィンドウ全体にStageを拡張して描画する。`false` の場合は `width`・`height` で指定したサイズで固定描画 |
+| `tagId` | string \| null | null | 描画先とするHTML要素のID。指定したIDのエレメント内部にキャンバスが生成される。`null` の場合は `<body>` 直下に生成される |
+| `bgColor` | string | "transparent" | 背景色を16進数カラーコードで指定（例: `"#1461A0"`）。`"transparent"` を指定すると透明になる |
+> [!WARNING]
+> `stage.json` で有効なプロパティは上記の `width`・`height`・`fps`・`options` のみです。
+> `align`・`scaleMode` などステージ表示に関わる設定であっても、`stage.json` には存在しないプロパティです。
+> これらの設定が必要な場合は `config.json` に記述してください。
+> 上記以外のプロパティを記述しても、フレームワークは一切処理しません。
+---
 ## config.json
-環境ごとの設定を管理するファイルです。`local`、`dev`、`stg`、`prd`、`all`と区切られており、`all`以外は任意の環境名です。
+環境ごとの設定を管理するファイルです。ビルド時に `--env` オプションで指定した環境名のオブジェクトと `all` オブジェクトがマージされ、アプリケーション全体で参照可能な設定として展開されます。
 ```json
 {
@@ -584,20 +594,68 @@ src/config/
 }
 ```
-### all設定
+### 環境キーの仕様
+`local`・`dev`・`stg`・`prd` などのキー名は任意です（`all` を除く）。ビルド時に `--env=<環境名>` で一致したキーのオブジェクトが読み込まれます。
+| キー | 説明 |
+|------|------|
+| `all` | すべての環境で共通して読み込まれる設定 |
+| それ以外 | `--env` で指定した環境名と一致したときのみ読み込まれる設定 |
-`all`はどの環境でも書き出される共通変数です。
+### all 設定（フレームワーク予約済みプロパティ）
+以下のプロパティはフレームワークが自動的に処理します。
 | プロパティ | 型 | デフォルト | 説明 |
 |-----------|------|----------|------|
-| `spa` | boolean | true | Single Page ApplicationとしてURLでシーンを制御 |
-| `defaultTop` | string | "top" | ページトップのView。設定がない場合はTopViewクラスが起動 |
-| `loading.callback` | string | Loading | ローディング画面のクラス名。start関数とend関数を呼び出す |
-| `gotoView.callback` | string \| array | ["callback.Background"] | gotoView完了後のコールバッククラス |
+| `spa` | boolean | true | `true` にするとSingle Page Applicationとして動作し、ブラウザのURLと連動してView遷移を管理する |
+| `defaultTop` | string | "top" | アプリ起動時に最初に表示するViewの名前。指定しない場合は `TopView` クラスが起動する |
+| `loading.callback` | string | "Loading" | ローディング画面として使用するクラス名。そのクラスの `start()` と `end()` が自動的に呼び出される |
+| `gotoView.callback` | string \| string[] | — | View遷移完了後に呼び出すコールバッククラス名。配列で複数指定でき、async/awaitで順次実行される |
+### ユーザー定義プロパティ
-### platform設定
+フレームワークの予約済みプロパティ以外に、任意のプロパティをどの環境キーにも追加できます。追加したプロパティはビルド後に `config` オブジェクトから参照できます。
-ビルド時の`--platform`で指定した値がセットされます。
+エンドポイントURLや機能フラグ、表示設定など、環境ごとに変える必要がある値をここで管理します。
+```json
+{
+    "local": {
+        "api": {
+            "endPoint": "http://localhost:3000/"
+        }
+    },
+    "prd": {
+        "api": {
+            "endPoint": "https://api.example.com/"
+        }
+    },
+    "all": {
+        "spa": true,
+        "defaultTop": "top",
+        "align": "TL",
+        "scaleMode": "noScale"
+    }
+}
+```
+```typescript
+import { config } from "@/config/Config";
+// ユーザー定義プロパティへのアクセス
+const align     = config.align;     // "TL"
+const scaleMode = config.scaleMode; // "noScale"
+```
+> [!WARNING]
+> `config.json` でフレームワークが自動処理するプロパティは `spa`・`defaultTop`・`loading`・`gotoView` のみです。
+> それ以外のプロパティはフレームワークが直接処理することはありませんが、`config` オブジェクト経由でアプリケーションコードから自由に参照できます。
+### platform 設定
+ビルド時の `--platform` で指定した値が自動的にセットされます。設定ファイルに記述する必要はなく、読み取り専用です。
 対応値: `macos`, `windows`, `linux`, `ios`, `android`, `web`
@@ -609,6 +667,8 @@ if (config.platform === "ios") {
 }
 ```
+---
 ## routing.json
 ルーティングの設定ファイルです。詳細は[ルーティング](/ja/reference/framework/routing)を参照してください。
@@ -630,45 +690,13 @@ if (config.platform === "ios") {
 }
 ```
-## 設定値の取得
-コード内で設定値を取得するには`config`オブジェクトを使用します。
-### Config.tsの例
+---
-```typescript
-import stageJson from "./stage.json";
-import configJson from "./config.json";
-interface IStageConfig {
-    width: number;
-    height: number;
-    fps: number;
-    options: {
-        fullScreen: boolean;
-        tagId: string | null;
-        bgColor: string;
-    };
-}
+## 設定値の取得
-interface IConfig {
-    stage: IStageConfig;
-    api: {
-        endPoint: string;
-    };
-    content: {
-        endPoint: string;
-    };
-    spa: boolean;
-    defaultTop: string;
-    platform: string;
-}
+`Config.ts` は `npm start` 実行時に自動生成されるファイルです。手動で作成・編集する必要はありません。
-export const config: IConfig = {
-    stage: stageJson,
-    ...configJson
-};
-```
+コード内で設定値を取得するには、自動生成された `config` オブジェクトをインポートして使用します。
 ### 使用例
@@ -676,7 +704,7 @@ export const config: IConfig = {
 import { config } from "@/config/Config";
 // ステージ設定
-const stageWidth = config.stage.width;
+const stageWidth  = config.stage.width;
 const stageHeight = config.stage.height;
 // API設定
@@ -686,9 +714,11 @@ const apiEndPoint = config.api.endPoint;
 const isSpa = config.spa;
 ```
+---
 ## ローディング画面
-`loading.callback`で設定したクラスの`start`関数と`end`関数が呼び出されます。
+`loading.callback` で設定したクラスの `start()` と `end()` が自動的に呼び出されます。
 ```typescript
 export class Loading
@@ -715,9 +745,11 @@ export class Loading
 }
 ```
-## gotoViewコールバック
+---
-`gotoView.callback`で設定したクラスの`execute`関数が呼び出されます。複数のクラスを配列で設定でき、async/awaitで順次実行されます。
+## gotoView コールバック
+`gotoView.callback` で設定したクラスの `execute()` が呼び出されます。配列で複数のクラスを指定でき、async/await で順次実行されます。
 ```typescript
 import { app } from "@next2d/framework";
@@ -744,6 +776,8 @@ export class Background
 }
 ```
+---
 ## ビルドコマンド
 環境を指定してビルド:
@@ -767,6 +801,8 @@ npm run build -- --platform=ios
 npm run build -- --platform=android
 ```
+---
 ## 設定例
 ### 完全な設定ファイルの例
@@ -822,11 +858,15 @@ npm run build -- --platform=android
         },
         "gotoView": {
             "callback": ["callback.Background"]
-        }
+        },
+        "align": "TL",
+        "scaleMode": "noScale"
     }
 }
 ```
+---
 ## 関連項目
 - [ルーティング](/ja/reference/framework/routing)
@@ -1068,15 +1108,6 @@ export class HomeDataCallback
 - 引数を省略した場合は、現在のURLから遷移先が解決されます（SPAの`popstate`時）。
 - 遷移開始時に前回の`response`マップはクリアされます。
-`gotoView`実行シーケンス（詳細）:
-1. 前回遷移で保持していた`response`マップを初期化します。
-2. `name`または現在URLから遷移先ルートを解決し、クエリを分解します。
-3. `all.spa: true`かつ通常遷移時はHistory API（`pushState`）でURL履歴を更新します。
-4. 遷移先`requests`を実行し、`name`キー単位で`response`/`cache`へ格納します。
-5. `requests.callback`と`gotoView.callback`を順次実行します。
-6. 旧Viewの`onExit`/unbind後に新View/ViewModelをbindし、`initialize`完了後に`onEnter`を呼び出します。
 ```typescript
 import { app } from "@next2d/framework";
@@ -1699,6 +1730,108 @@ homeContentPointerDownEvent(event: PointerEvent): void
 View内でイベント処理を完結させず、必ずViewModelに委譲します。
+### 4. `addEventListener` に `async` 関数を直接渡さない
+**NG パターン（Promiseエラーの原因）:**
+```typescript
+btn.addEventListener(PointerEvent.POINTER_DOWN, async () =>
+{
+    await this.vm.onClickSomething();
+});
+```
+`async` 関数は Promise を返します。@next2d/player の内部イベントシステムは、
+ハンドラが truthy な値を返すと「非同期応答あり」と解釈し、Worker との
+メッセージチャンネルを保持します。SPA 遷移で `gotoView()` が呼ばれると
+チャンネルが閉じられ、以下のエラーが `Uncaught (in promise)` として発生します。
+```
+A listener indicated an asynchronous response by returning true,
+but the message channel closed before a response was received
+```
+**OK パターン（`void (async () => {})()` でラップ）:**
+```typescript
+btn.addEventListener(PointerEvent.POINTER_DOWN, () =>
+{
+    if (!btn.enabled) { return; }        // 同期ガードはここで
+    btn.disable();
+    void (async () =>
+    {
+        try {
+            await this.vm.onClickSomething();
+        } catch (error) {
+            btn.enable();
+            console.error("[prefix]", "遷移に失敗", error);
+        }
+    })();
+});
+```
+ポイント:
+- 外側のハンドラを **同期関数** にして `void` 以外の戻り値を返さない
+- `await` が必要な処理は内側の即時実行 async IIFE に閉じ込め、`void` で破棄
+- `enabled` チェックなど即時判断が必要なガードは **外側の同期ハンドラ** に置く
+### 5. SPA 遷移時の「メッセージチャンネルクローズ」エラーを防ぐ
+**エラーメッセージ:**
+```
+Uncaught (in promise) Error: A listener indicated an asynchronous response
+by returning true, but the message channel closed before a response was received
+```
+**発生メカニズム（2つの独立した原因）:**
+| # | 原因 | 性質 | 対処 |
+|---|------|------|------|
+| ① | `addEventListener` に `async` 関数を直接渡した（Promise を返すため） | JavaScript Promise rejection | 設計原則4の `void (async () => {})()` パターンで修正 |
+| ② | @next2d/player が `app.initialize()` 完了後に DOM 追加する IME 用 `<textarea tabindex="-1">` を Chrome 拡張機能（パスワードマネージャー等）が検出し、SPA 遷移でチャンネルが閉じる | **Chrome 拡張機能のランタイムエラー**（JS Promise rejection ではない） | 初期化後に textarea へ `autocomplete="off"` 等を設定して拡張機能の検出を抑制 |
+> **重要:** 原因②は JavaScript の Promise rejection ではなく Chrome 拡張機能のランタイムエラーです。
+> そのため `window.addEventListener("unhandledrejection", ...)` では**捕捉・抑制できません**。
+> `unhandledrejection` ハンドラは原因①（コード起因）の残存ケースに対する安全網として追加します。
+**アプリエントリポイント (`index.ts`) への対処:**
+```typescript
+// ① コード起因の Promise rejection が残存する場合の安全網（unhandledrejection で捕捉可能）
+//    原因②（Chrome 拡張起因）はここでは捕捉できないため、別途 textarea 対策が必要
+window.addEventListener("unhandledrejection", (event) =>
+{
+    const reason = event.reason;
+    const message = (typeof reason === "string"
+        ? reason
+        : (reason as { message?: string } | null)?.message) ?? "";
+    if (message.includes("A listener indicated an asynchronous response by returning true")) {
+        event.preventDefault();
+    }
+});
+const boot = async (): Promise<void> =>
+{
+    await app.initialize(config, packages).run();
+    // ② @next2d/player の IME 用グローバル textarea に Chrome 拡張が干渉するのを防ぐ
+    //    tabIndex="-1" の textarea は @next2d/player が app.initialize() 完了時に DOM 追加する
+    //    Chrome の自動補完やパスワードマネージャーがこの textarea を検出すると
+    //    SPA 遷移時にメッセージチャンネルエラーが発生する（JS Promise rejection ではなく
+    //    Chrome 拡張のランタイムエラーのため unhandledrejection ハンドラでは捕捉不可）
+    const internalTextarea = document.querySelector('textarea[tabindex="-1"]');
+    if (internalTextarea) {
+        internalTextarea.setAttribute("autocomplete", "off");
+        internalTextarea.setAttribute("data-form-type", "other");
+        internalTextarea.setAttribute("role", "presentation");
+        internalTextarea.setAttribute("aria-hidden", "true");
+    }
+    await app.gotoView();
+};
+```
 ## View/ViewModel作成のテンプレート
 ### View

package/package.json CHANGED Viewed

@@ -1,7 +1,7 @@
 {
   "name": "next2d-development-mcp",
   "displayName": "Next2D Development MCP",
-  "version": "1.1.4",
+  "version": "1.1.6",
   "description": "MCP server for Next2D application development assistance",
   "type": "module",
   "author": "Toshiyuki Ienaga <ienaga@next2d.app>",
@@ -52,19 +52,19 @@
   },
   "devDependencies": {
     "@eslint/js": "^10.0.1",
-    "@types/node": "^25.5.2",
-    "@types/vscode": "^1.110.0",
-    "@typescript-eslint/eslint-plugin": "^8.58.0",
-    "@typescript-eslint/parser": "^8.58.0",
-    "@vscode/vsce": "^3.7.1",
-    "eslint": "^10.2.0",
+    "@types/node": "^25.6.2",
+    "@types/vscode": "^1.115.0",
+    "@typescript-eslint/eslint-plugin": "^8.59.2",
+    "@typescript-eslint/parser": "^8.59.2",
+    "@vscode/vsce": "^3.9.1",
+    "eslint": "^10.3.0",
     "eslint-plugin-unused-imports": "^4.4.1",
-    "globals": "^17.4.0",
-    "typescript": "^6.0.2",
-    "vitest": "^4.1.2"
+    "globals": "^17.6.0",
+    "typescript": "^6.0.3",
+    "vitest": "^4.1.5"
   },
   "engines": {
     "node": ">=22.0.0",
-    "vscode": "^1.109.0"
+    "vscode": "^1.115.0"
   }
 }