@kubohiroya/turbowarp-title-menu 0.1.0 → 0.2.1

package/README.ja.md

@@ -11,7 +11,7 @@ TurboWarp拡張やPackager実行環境で使える、汎用のタイトル表示
 ## できること
 
 - 起動直後のタイトル表示として、タイトル、作者名、ライセンス、公式Webサイト、閉じるボタンを表示します。
-- ステージ上にアプリケーションメニューを表示します。共有primitiveの`@kubohiroya/turbowarp-app-shell`の上に作っているため、ホスト側は固定の項目ではなく自分の操作を定義できます。
+- ステージ上にアプリケーションメニューを表示します。共有primitiveの`@kubohiroya/turbowarp-app-shell`の上に作っており、項目はblockから定義してhatで受けられるため、固定の項目に縛られません。
 - DSLファイル管理ダイアログで、追加、開く、名前の変更、個別削除ができ、名前・更新日時・サイズで並べ替えできます。
 - 複数のDSLファイルをIndexedDBに保管します。TM Kamishibai専用ではありません。
 - ホスト側ランタイムから直接組み込める Composition API を提供します。
@@ -33,7 +33,7 @@ IndexedDBはoriginごとに分かれます。TurboWarp Web、TurboWarp Desktop
 ## インストール
 
 ```bash
-pnpm add --save-exact @kubohiroya/turbowarp-title-menu@0.1.0
+pnpm add --save-exact @kubohiroya/turbowarp-title-menu@0.2.1
 ```
 
 TurboWarpでは `dist/turbowarp-title-menu.js` をCustom Extensionとして読み込み、sandboxなしの実行を許可します。
@@ -49,6 +49,19 @@ when green flag clicked
 show title dialog
 ```
 
+メニューは4つの組み込み項目から始まります。合わない場合は、プロジェクト自身の語彙に置き換えます。
+
+```text
+when green flag clicked
+clear app menu actions
+add app menu action [pair] labelled [統合PCとつなぐ]
+add app menu action [calibrate] labelled [カメラを校正する]
+show application menu
+
+when app menu action [pair v] selected
+broadcast [start pairing v]
+```
+
 DSLを読み込んだ後の処理は `when a DSL source is opened` から始めます。
 
 ```text
@@ -76,6 +89,42 @@ TurboWarpステージ上にアプリケーションメニューを表示しま
 | Type | Command |
 | Opcode | `showMenu` |
 
+### `add app menu action [ACTION] labelled [LABEL]`
+
+このプロジェクトが持つメニュー項目を追加します。すでに追加済みのIDなら表示名を変更します。
+
+| Property | Value |
+|---|---|
+| Type | Command |
+| Opcode | `addAppMenuAction` |
+
+### `clear app menu actions`
+
+組み込みを含め、すべてのメニュー項目を削除します。プロジェクト自身の項目だけにしたいときに使います。
+
+| Property | Value |
+|---|---|
+| Type | Command |
+| Opcode | `clearAppMenuActions` |
+
+### `set app menu action [ACTION] enabled [ENABLED]`
+
+メニュー項目の1つを有効／無効にします。
+
+| Property | Value |
+|---|---|
+| Type | Command |
+| Opcode | `setAppMenuActionEnabled` |
+
+### `when app menu action [ACTION] selected`
+
+運用者がそのメニュー項目を選んだときに実行されます。
+
+| Property | Value |
+|---|---|
+| Type | Hat |
+| Opcode | `whenAppMenuActionSelected` |
+
 ### `show DSL file manager`
 
 保管したDSLファイルの追加、開く、名前の変更、削除、並べ替えを行うダイアログを表示します。
@@ -152,6 +201,9 @@ IndexedDBに保管しているDSLファイルの件数を返します。
 
 | 場面 | 動作 |
 |---|---|
+| 組み込みのメニュー項目 | `files`／`reload`／`about`／`close` は最初から登録されており、それぞれの動作を保ちます。同時にhatも発火します。`clear app menu actions` で外せます。 |
+| メニューの変更 | 項目の追加や消去でメニューを作り直します。表示中だった場合は消えずに再表示します。 |
+| 項目が0件のとき | 1件も登録されていない状態では `show application menu` は何もせず、すべて消すと表示中のメニューは閉じます。土台のprimitiveが0件のメニューを作れないため、自分の項目を入れる前に全消しするプロジェクトが途中で止まらないようにしています。 |
 | ファイルの追加 | 「ファイルを追加」はファイル選択ダイアログを開き、選ばれた内容を保管します。開きはしません。使うときは「開く」を押します。 |
 | 名前の変更 | 名前は一意です。他のファイルと同じ名前にしようとすると失敗し、どちらのファイルも変わりません。 |
 | 削除 | 削除には確認のためもう一度クリックが必要です。開いているファイルを削除すると、開いている内容も解除されます。 |

package/README.md

@@ -9,7 +9,7 @@ Reusable title, application menu, and DSL source storage controls for TurboWarp
 ## What it does
 
 - Shows a reusable title dialog with title, author, license, official website, language, and close controls.
-- Shows a stage-mounted application menu built on the shared `@kubohiroya/turbowarp-app-shell` primitive, so a host project can define its own actions instead of a fixed set.
+- Shows a stage-mounted application menu built on the shared `@kubohiroya/turbowarp-app-shell` primitive. A project defines its own actions from blocks and reacts to them with a hat, so the menu is not limited to a fixed set.
 - Shows a DSL file manager that adds, opens, renames, and deletes stored files, and sorts them by name, update time, or size.
 - Stores many DSL files in IndexedDB without tying the mechanism to TM Kamishibai.
 - Exposes a small Composition API for projects that want to wire the controls into their own runtime.
@@ -48,7 +48,7 @@ The reviewed JavaScript build is committed to this repository, so users do not n
 Install an exact version that you have reviewed:
 
 ```bash
-pnpm add --save-exact @kubohiroya/turbowarp-title-menu@0.1.0
+pnpm add --save-exact @kubohiroya/turbowarp-title-menu@0.2.1
 ```
 
 Load the standalone bundle from:
@@ -60,7 +60,7 @@ node_modules/@kubohiroya/turbowarp-title-menu/dist/turbowarp-title-menu.js
 A version-pinned CDN URL is:
 
 ```text
-https://cdn.jsdelivr.net/npm/@kubohiroya/turbowarp-title-menu@0.1.0/dist/turbowarp-title-menu.js
+https://cdn.jsdelivr.net/npm/@kubohiroya/turbowarp-title-menu@0.2.1/dist/turbowarp-title-menu.js
 ```
 
 ## Quick start
@@ -69,6 +69,20 @@ https://cdn.jsdelivr.net/npm/@kubohiroya/turbowarp-title-menu@0.1.0/dist/turbowa
 2. Run `show title dialog` immediately after startup.
 3. Use `show application menu`, or `show DSL file manager` directly, when the project should expose DSL file actions.
 
+The menu starts with four built-in actions. Replace them with the project's own vocabulary when the
+built-in ones do not fit:
+
+```text
+when green flag clicked
+clear app menu actions
+add app menu action [pair] labelled [Pair with fusion PC]
+add app menu action [calibrate] labelled [Calibrate camera]
+show application menu
+
+when app menu action [pair v] selected
+broadcast [start pairing v]
+```
+
 ```text
 when green flag clicked
 show title dialog
@@ -98,6 +112,47 @@ Shows the application menu above the TurboWarp stage.
 | Type | Command |
 | Opcode | `showMenu` |
 
+### `add app menu action [ACTION] labelled [LABEL]`
+
+Adds an application menu action this project owns, or relabels one it already added.
+
+| Property | Value |
+|---|---|
+| Type | Command |
+| Opcode | `addAppMenuAction` |
+| `ACTION` | String, default: `start` |
+| `LABEL` | String, default: `Start` |
+
+### `clear app menu actions`
+
+Removes every application menu action, including the built-in ones, so a project can define its own set.
+
+| Property | Value |
+|---|---|
+| Type | Command |
+| Opcode | `clearAppMenuActions` |
+
+### `set app menu action [ACTION] enabled [ENABLED]`
+
+Enables or disables one application menu action.
+
+| Property | Value |
+|---|---|
+| Type | Command |
+| Opcode | `setAppMenuActionEnabled` |
+| `ACTION` | String, default: `undefined` |
+| `ENABLED` | Boolean, default: `true` |
+
+### `when app menu action [ACTION] selected`
+
+Runs when the operator selects the named application menu action.
+
+| Property | Value |
+|---|---|
+| Type | Hat |
+| Opcode | `whenAppMenuActionSelected` |
+| `ACTION` | String, default: `undefined` |
+
 ### `show DSL file manager`
 
 Shows the dialog that adds, opens, renames, deletes, and sorts stored DSL files.
@@ -178,6 +233,9 @@ Returns the most recent DSL storage failure in the interface language, or an emp
 |---|---|
 | Startup title | `show title dialog` mounts a dialog over the stage and keeps Scratch sprites untouched. |
 | Official website | The title dialog opens the configured website URL in a new browser tab. |
+| Built-in menu actions | `files`, `reload`, `about`, and `close` are pre-registered and keep their own behavior. They also start the hat, and `clear app menu actions` removes them. |
+| Changing the menu | Adding or clearing an action rebuilds the menu. A menu that was on screen is shown again rather than disappearing. |
+| An empty menu | `show application menu` does nothing while no action is registered, and clearing every action closes an open menu. The underlying primitive refuses to build a menu with no actions, so a project that clears the set before installing its own is not interrupted. |
 | Adding a DSL file | `Add file` opens a browser file picker and stores the chosen source. It does not open the file; the operator presses `Open` when the project should use it. |
 | Renaming | Names are unique. Renaming a file to a name another file already uses fails and leaves both files unchanged. |
 | Deleting | Deleting asks for a second confirming click, and deleting the open file clears the opened source. |

package/dist/extension-manifest.json

@@ -2,6 +2,25 @@
   "formatVersion": 1,
   "id": "kubohiroyaturbowarptitlemenu",
   "blocks": [
+    {
+      "opcode": "addAppMenuAction",
+      "blockType": "COMMAND",
+      "arguments": [
+        {
+          "id": "ACTION",
+          "type": "STRING"
+        },
+        {
+          "id": "LABEL",
+          "type": "STRING"
+        }
+      ]
+    },
+    {
+      "opcode": "clearAppMenuActions",
+      "blockType": "COMMAND",
+      "arguments": []
+    },
     {
       "opcode": "hasSavedDsl",
       "blockType": "BOOLEAN",
@@ -32,6 +51,21 @@
       "blockType": "REPORTER",
       "arguments": []
     },
+    {
+      "opcode": "setAppMenuActionEnabled",
+      "blockType": "COMMAND",
+      "arguments": [
+        {
+          "id": "ACTION",
+          "type": "STRING",
+          "menu": "menuActions"
+        },
+        {
+          "id": "ENABLED",
+          "type": "BOOLEAN"
+        }
+      ]
+    },
     {
       "opcode": "showDslFiles",
       "blockType": "COMMAND",
@@ -47,11 +81,27 @@
       "blockType": "COMMAND",
       "arguments": []
     },
+    {
+      "opcode": "whenAppMenuActionSelected",
+      "blockType": "HAT",
+      "arguments": [
+        {
+          "id": "ACTION",
+          "type": "STRING",
+          "menu": "menuActions"
+        }
+      ]
+    },
     {
       "opcode": "whenDslSourceOpened",
       "blockType": "HAT",
       "arguments": []
     }
   ],
-  "menus": []
+  "menus": [
+    {
+      "id": "menuActions",
+      "acceptReporters": true
+    }
+  ]
 }

package/dist/turbowarp-title-menu.js

@@ -1183,9 +1183,11 @@
     });
   }
   const extensionName = "TurboWarp Title Menu";
-  const blocks = [{ "opcode": "showTitle", "blockType": "COMMAND", "text": "show title dialog", "description": "Shows the configured title dialog above the TurboWarp stage." }, { "opcode": "showMenu", "blockType": "COMMAND", "text": "show application menu", "description": "Shows the application menu above the TurboWarp stage." }, { "opcode": "showDslFiles", "blockType": "COMMAND", "text": "show DSL file manager", "description": "Shows the dialog that adds, opens, renames, deletes, and sorts stored DSL files." }, { "opcode": "whenDslSourceOpened", "blockType": "HAT", "text": "when a DSL source is opened", "description": "Runs after the operator opens a stored DSL file, or after the opened source is announced again." }, { "opcode": "reloadOpenedDsl", "blockType": "COMMAND", "text": "reload the opened DSL source", "description": "Announces the currently opened DSL source again without showing a dialog." }, { "opcode": "openedDslName", "blockType": "REPORTER", "text": "opened DSL file name", "description": "Returns the name of the DSL file that is currently open, or an empty string." }, { "opcode": "openedDslSource", "blockType": "REPORTER", "text": "opened DSL source", "description": "Returns the text of the DSL file that is currently open, or an empty string." }, { "opcode": "hasSavedDsl", "blockType": "BOOLEAN", "text": "has a saved DSL file?", "description": "Reports whether at least one DSL file is stored in IndexedDB." }, { "opcode": "savedDslCount", "blockType": "REPORTER", "text": "saved DSL file count", "description": "Returns how many DSL files are stored in IndexedDB." }, { "opcode": "lastDslError", "blockType": "REPORTER", "text": "last DSL storage error", "description": "Returns the most recent DSL storage failure in the interface language, or an empty string." }];
+  const menus = { "menuActions": { "acceptReporters": true, "items": "menuActionItems" } };
+  const blocks = [{ "opcode": "showTitle", "blockType": "COMMAND", "text": "show title dialog", "description": "Shows the configured title dialog above the TurboWarp stage." }, { "opcode": "showMenu", "blockType": "COMMAND", "text": "show application menu", "description": "Shows the application menu above the TurboWarp stage." }, { "opcode": "addAppMenuAction", "blockType": "COMMAND", "text": "add app menu action [ACTION] labelled [LABEL]", "description": "Adds an application menu action this project owns, or relabels one it already added.", "arguments": { "ACTION": { "type": "STRING", "defaultValue": "start" }, "LABEL": { "type": "STRING", "defaultValue": "Start" } } }, { "opcode": "clearAppMenuActions", "blockType": "COMMAND", "text": "clear app menu actions", "description": "Removes every application menu action, including the built-in ones, so a project can define its own set." }, { "opcode": "setAppMenuActionEnabled", "blockType": "COMMAND", "text": "set app menu action [ACTION] enabled [ENABLED]", "description": "Enables or disables one application menu action.", "arguments": { "ACTION": { "type": "STRING", "menu": "menuActions" }, "ENABLED": { "type": "BOOLEAN", "defaultValue": true } } }, { "opcode": "whenAppMenuActionSelected", "blockType": "HAT", "text": "when app menu action [ACTION] selected", "description": "Runs when the operator selects the named application menu action.", "arguments": { "ACTION": { "type": "STRING", "menu": "menuActions" } } }, { "opcode": "showDslFiles", "blockType": "COMMAND", "text": "show DSL file manager", "description": "Shows the dialog that adds, opens, renames, deletes, and sorts stored DSL files." }, { "opcode": "whenDslSourceOpened", "blockType": "HAT", "text": "when a DSL source is opened", "description": "Runs after the operator opens a stored DSL file, or after the opened source is announced again." }, { "opcode": "reloadOpenedDsl", "blockType": "COMMAND", "text": "reload the opened DSL source", "description": "Announces the currently opened DSL source again without showing a dialog." }, { "opcode": "openedDslName", "blockType": "REPORTER", "text": "opened DSL file name", "description": "Returns the name of the DSL file that is currently open, or an empty string." }, { "opcode": "openedDslSource", "blockType": "REPORTER", "text": "opened DSL source", "description": "Returns the text of the DSL file that is currently open, or an empty string." }, { "opcode": "hasSavedDsl", "blockType": "BOOLEAN", "text": "has a saved DSL file?", "description": "Reports whether at least one DSL file is stored in IndexedDB." }, { "opcode": "savedDslCount", "blockType": "REPORTER", "text": "saved DSL file count", "description": "Returns how many DSL files are stored in IndexedDB." }, { "opcode": "lastDslError", "blockType": "REPORTER", "text": "last DSL storage error", "description": "Returns the most recent DSL storage failure in the interface language, or an empty string." }];
   const definitions = {
     extensionName,
+    menus,
     blocks
   };
   const titleLocales = Object.freeze({
@@ -1273,6 +1275,7 @@
   }
   const blockDefinitions = definitions.blocks;
   const dslFileAccept = ".txt,.yaml,.yml,.json,.k4,.kamishibai";
+  const builtinActionIds = ["files", "reload", "about", "close"];
   function stageMount() {
     return Scratch.vm?.renderer?.canvas?.parentElement ?? globalThis.document?.body;
   }
@@ -1284,6 +1287,12 @@
       this.store = null;
       this.openedRecord = null;
       this.lastError = "";
+      this.menuActions = builtinActionIds.map((id) => ({
+        id,
+        labels: { en: menuLocales.en[id], ja: menuLocales.ja[id] },
+        enabled: true
+      }));
+      this.menuVisible = false;
     }
     getInfo() {
       return {
@@ -1291,14 +1300,57 @@
         name: Scratch.translate(definitions.extensionName),
         docsURI: extensionConfig.docsURI,
         blockIconURI: extensionConfig.blockIconURI,
-        blocks: blockDefinitions.map((block) => this.toScratchBlock(block))
+        blocks: blockDefinitions.map((block) => this.toScratchBlock(block)),
+        menus: definitions.menus
       };
     }
     showTitle() {
       this.ensureTitleDialog().show(this.locale());
     }
+    /**
+     * Shows the application menu.
+     *
+     * An empty registry does nothing: the underlying primitive requires at least one action, and a
+     * project that cleared the actions to install its own should not be interrupted by an error
+     * between the two steps.
+     */
     showMenu() {
+      if (this.menuActions.length === 0) return;
       this.ensureApplicationMenu().show(this.locale());
+      this.menuVisible = true;
+    }
+    /** Backs the dynamic `menuActions` dropdown, so it always lists what the project registered. */
+    menuActionItems() {
+      if (this.menuActions.length === 0) return [{ text: "—", value: "" }];
+      const locale = this.locale();
+      return this.menuActions.map((action) => ({ text: action.labels[locale], value: action.id }));
+    }
+    addAppMenuAction(args) {
+      const id = Scratch.Cast.toString(args.ACTION).trim();
+      if (id.length === 0) return;
+      const label = Scratch.Cast.toString(args.LABEL);
+      const existing = this.menuActions.find((action) => action.id === id);
+      if (existing === void 0) {
+        this.menuActions.push({ id, labels: { en: label, ja: label }, enabled: true });
+      } else {
+        existing.labels = { en: label, ja: label };
+      }
+      this.rebuildMenu();
+    }
+    clearAppMenuActions() {
+      this.menuActions = [];
+      this.rebuildMenu();
+    }
+    setAppMenuActionEnabled(args) {
+      const id = Scratch.Cast.toString(args.ACTION);
+      const action = this.menuActions.find((entry) => entry.id === id);
+      if (action === void 0) return;
+      action.enabled = Scratch.Cast.toBoolean(args.ENABLED);
+      this.applicationMenu?.setActionState(id, { enabled: action.enabled });
+    }
+    /** Started by the menu callback, so the handler only has to accept the match. */
+    whenAppMenuActionSelected() {
+      return true;
     }
     showDslFiles() {
       return this.ensureFilesDialog().show(this.locale());
@@ -1347,6 +1399,36 @@
     recordFailure(error) {
       this.lastError = describeStoreError(this.locale(), error);
     }
+    /**
+     * Rebuilds the menu after its action list changed.
+     *
+     * The app-shell primitive fixes its actions at construction, so a changed list means a new menu.
+     * A menu that was on screen is shown again, because a project that adds an action while the menu
+     * is open should not have it silently disappear. Clearing every action closes the menu instead,
+     * because the primitive refuses to build one with no actions.
+     */
+    rebuildMenu() {
+      this.applicationMenu?.dispose();
+      this.applicationMenu = null;
+      if (!this.menuVisible) return;
+      if (this.menuActions.length === 0) {
+        this.menuVisible = false;
+        return;
+      }
+      this.showMenu();
+    }
+    selectMenuAction(id) {
+      Scratch.vm?.runtime?.startHats?.(`${extensionConfig.id}_whenAppMenuActionSelected`, { ACTION: id });
+      if (!builtinActionIds.includes(id)) return;
+      if (id === "files") void this.showDslFiles();
+      if (id === "reload") this.reloadOpenedDsl();
+      if (id === "about") this.showTitle();
+      if (id === "close") this.hideMenu();
+    }
+    hideMenu() {
+      this.applicationMenu?.hide();
+      this.menuVisible = false;
+    }
     announce(eventName, record) {
       dispatchDslSourceEvent(eventName, record);
       Scratch.vm?.runtime?.startHats?.(`${extensionConfig.id}_whenDslSourceOpened`);
@@ -1374,20 +1456,16 @@
       if (this.applicationMenu) return this.applicationMenu;
       const mount = stageMount();
       if (mount === void 0) throw new TypeError("a stage container is required to show the menu");
-      const labels = (key) => ({
-        en: menuLocales.en[key],
-        ja: menuLocales.ja[key]
-      });
       this.applicationMenu = createAppShellApplicationMenu({
         document: globalThis.document,
         mount,
         initialLocale: this.locale(),
-        actions: [
-          { id: "files", labels: labels("files"), icon: { text: "📂" }, onSelect: () => this.showDslFiles() },
-          { id: "reload", labels: labels("reload"), icon: { text: "↻" }, onSelect: () => this.reloadOpenedDsl() },
-          { id: "about", labels: labels("about"), icon: { text: "i" }, onSelect: () => this.showTitle() },
-          { id: "close", labels: labels("close"), icon: { text: "x" }, onSelect: () => this.applicationMenu?.hide() }
-        ]
+        actions: this.menuActions.map((action) => ({
+          id: action.id,
+          labels: action.labels,
+          enabled: action.enabled,
+          onSelect: () => this.selectMenuAction(action.id)
+        }))
       });
       return this.applicationMenu;
     }
@@ -1456,7 +1534,8 @@
             name,
             {
               type: Scratch.ArgumentType[argument.type],
-              defaultValue: argument.defaultValue
+              ...argument.defaultValue === void 0 ? {} : { defaultValue: argument.defaultValue },
+              ...argument.menu === void 0 ? {} : { menu: argument.menu }
             }
           ])
         )

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kubohiroya/turbowarp-title-menu",
-  "version": "0.1.0",
+  "version": "0.2.1",
   "description": "Reusable title, application menu, and DSL source storage controls for TurboWarp.",
   "author": "Hiroya Kubo <hiroya@cuc.ac.jp>",
   "license": "MPL-2.0",

package/src/block-definitions.json

@@ -1,5 +1,11 @@
 {
   "extensionName": "TurboWarp Title Menu",
+  "menus": {
+    "menuActions": {
+      "acceptReporters": true,
+      "items": "menuActionItems"
+    }
+  },
   "blocks": [
     {
       "opcode": "showTitle",
@@ -13,6 +19,56 @@
       "text": "show application menu",
       "description": "Shows the application menu above the TurboWarp stage."
     },
+    {
+      "opcode": "addAppMenuAction",
+      "blockType": "COMMAND",
+      "text": "add app menu action [ACTION] labelled [LABEL]",
+      "description": "Adds an application menu action this project owns, or relabels one it already added.",
+      "arguments": {
+        "ACTION": {
+          "type": "STRING",
+          "defaultValue": "start"
+        },
+        "LABEL": {
+          "type": "STRING",
+          "defaultValue": "Start"
+        }
+      }
+    },
+    {
+      "opcode": "clearAppMenuActions",
+      "blockType": "COMMAND",
+      "text": "clear app menu actions",
+      "description": "Removes every application menu action, including the built-in ones, so a project can define its own set."
+    },
+    {
+      "opcode": "setAppMenuActionEnabled",
+      "blockType": "COMMAND",
+      "text": "set app menu action [ACTION] enabled [ENABLED]",
+      "description": "Enables or disables one application menu action.",
+      "arguments": {
+        "ACTION": {
+          "type": "STRING",
+          "menu": "menuActions"
+        },
+        "ENABLED": {
+          "type": "BOOLEAN",
+          "defaultValue": true
+        }
+      }
+    },
+    {
+      "opcode": "whenAppMenuActionSelected",
+      "blockType": "HAT",
+      "text": "when app menu action [ACTION] selected",
+      "description": "Runs when the operator selects the named application menu action.",
+      "arguments": {
+        "ACTION": {
+          "type": "STRING",
+          "menu": "menuActions"
+        }
+      }
+    },
     {
       "opcode": "showDslFiles",
       "blockType": "COMMAND",

package/src/extension.ts

@@ -17,11 +17,12 @@ import {createTitleDialog, type TitleDialog} from './title-dialog';
 type ApplicationMenu = ReturnType<typeof createAppShellApplicationMenu>;
 
 type BlockTypeName = 'COMMAND' | 'REPORTER' | 'BOOLEAN' | 'HAT';
-type ArgumentTypeName = 'STRING';
+type ArgumentTypeName = 'STRING' | 'NUMBER' | 'BOOLEAN';
 
 interface DefinitionArgument {
   type: ArgumentTypeName;
-  defaultValue: string;
+  defaultValue?: string | number | boolean;
+  menu?: string;
 }
 
 interface BlockDefinition {
@@ -36,6 +37,17 @@ const blockDefinitions = definitions.blocks as readonly BlockDefinition[];
 
 const dslFileAccept = '.txt,.yaml,.yml,.json,.k4,.kamishibai';
 
+/** Reserved action IDs the extension handles itself. A project may still remove or relabel them. */
+const builtinActionIds = ['files', 'reload', 'about', 'close'] as const;
+
+type BuiltinActionId = (typeof builtinActionIds)[number];
+
+interface MenuActionEntry {
+  id: string;
+  labels: Record<SupportedLocale, string>;
+  enabled: boolean;
+}
+
 function stageMount(): HTMLElement | undefined {
   return Scratch.vm?.renderer?.canvas?.parentElement ?? globalThis.document?.body;
 }
@@ -47,6 +59,12 @@ export class TurboWarpTitleMenuExtension implements TurboWarpExtension {
   private store: DslStore | null = null;
   private openedRecord: DslFileRecord | null = null;
   private lastError = '';
+  private menuActions: MenuActionEntry[] = builtinActionIds.map((id) => ({
+    id,
+    labels: {en: menuLocales.en[id], ja: menuLocales.ja[id]},
+    enabled: true
+  }));
+  private menuVisible = false;
 
   public getInfo(): Record<string, unknown> {
     return {
@@ -54,7 +72,8 @@ export class TurboWarpTitleMenuExtension implements TurboWarpExtension {
       name: Scratch.translate(definitions.extensionName),
       docsURI: extensionConfig.docsURI,
       blockIconURI: extensionConfig.blockIconURI,
-      blocks: blockDefinitions.map((block) => this.toScratchBlock(block))
+      blocks: blockDefinitions.map((block) => this.toScratchBlock(block)),
+      menus: definitions.menus
     };
   }
 
@@ -62,8 +81,55 @@ export class TurboWarpTitleMenuExtension implements TurboWarpExtension {
     this.ensureTitleDialog().show(this.locale());
   }
 
+  /**
+   * Shows the application menu.
+   *
+   * An empty registry does nothing: the underlying primitive requires at least one action, and a
+   * project that cleared the actions to install its own should not be interrupted by an error
+   * between the two steps.
+   */
   public showMenu(): void {
+    if (this.menuActions.length === 0) return;
     this.ensureApplicationMenu().show(this.locale());
+    this.menuVisible = true;
+  }
+
+  /** Backs the dynamic `menuActions` dropdown, so it always lists what the project registered. */
+  public menuActionItems(): Array<{text: string; value: string}> {
+    if (this.menuActions.length === 0) return [{text: '\u2014', value: ''}];
+    const locale = this.locale();
+    return this.menuActions.map((action) => ({text: action.labels[locale], value: action.id}));
+  }
+
+  public addAppMenuAction(args: {ACTION: unknown; LABEL: unknown}): void {
+    const id = Scratch.Cast.toString(args.ACTION).trim();
+    if (id.length === 0) return;
+    const label = Scratch.Cast.toString(args.LABEL);
+    const existing = this.menuActions.find((action) => action.id === id);
+    if (existing === undefined) {
+      this.menuActions.push({id, labels: {en: label, ja: label}, enabled: true});
+    } else {
+      existing.labels = {en: label, ja: label};
+    }
+    this.rebuildMenu();
+  }
+
+  public clearAppMenuActions(): void {
+    this.menuActions = [];
+    this.rebuildMenu();
+  }
+
+  public setAppMenuActionEnabled(args: {ACTION: unknown; ENABLED: unknown}): void {
+    const id = Scratch.Cast.toString(args.ACTION);
+    const action = this.menuActions.find((entry) => entry.id === id);
+    if (action === undefined) return;
+    action.enabled = Scratch.Cast.toBoolean(args.ENABLED);
+    this.applicationMenu?.setActionState(id, {enabled: action.enabled});
+  }
+
+  /** Started by the menu callback, so the handler only has to accept the match. */
+  public whenAppMenuActionSelected(): boolean {
+    return true;
   }
 
   public showDslFiles(): Promise<unknown> {
@@ -124,6 +190,39 @@ export class TurboWarpTitleMenuExtension implements TurboWarpExtension {
     this.lastError = describeStoreError(this.locale(), error);
   }
 
+  /**
+   * Rebuilds the menu after its action list changed.
+   *
+   * The app-shell primitive fixes its actions at construction, so a changed list means a new menu.
+   * A menu that was on screen is shown again, because a project that adds an action while the menu
+   * is open should not have it silently disappear. Clearing every action closes the menu instead,
+   * because the primitive refuses to build one with no actions.
+   */
+  private rebuildMenu(): void {
+    this.applicationMenu?.dispose();
+    this.applicationMenu = null;
+    if (!this.menuVisible) return;
+    if (this.menuActions.length === 0) {
+      this.menuVisible = false;
+      return;
+    }
+    this.showMenu();
+  }
+
+  private selectMenuAction(id: string): void {
+    Scratch.vm?.runtime?.startHats?.(`${extensionConfig.id}_whenAppMenuActionSelected`, {ACTION: id});
+    if (!builtinActionIds.includes(id as BuiltinActionId)) return;
+    if (id === 'files') void this.showDslFiles();
+    if (id === 'reload') this.reloadOpenedDsl();
+    if (id === 'about') this.showTitle();
+    if (id === 'close') this.hideMenu();
+  }
+
+  private hideMenu(): void {
+    this.applicationMenu?.hide();
+    this.menuVisible = false;
+  }
+
   private announce(eventName: string, record: DslFileRecord): void {
     dispatchDslSourceEvent(eventName, record);
     Scratch.vm?.runtime?.startHats?.(`${extensionConfig.id}_whenDslSourceOpened`);
@@ -153,20 +252,16 @@ export class TurboWarpTitleMenuExtension implements TurboWarpExtension {
     if (this.applicationMenu) return this.applicationMenu;
     const mount = stageMount();
     if (mount === undefined) throw new TypeError('a stage container is required to show the menu');
-    const labels = (key: keyof (typeof menuLocales)['en']) => ({
-      en: menuLocales.en[key],
-      ja: menuLocales.ja[key]
-    });
     this.applicationMenu = createAppShellApplicationMenu({
       document: globalThis.document,
       mount,
       initialLocale: this.locale(),
-      actions: [
-        {id: 'files', labels: labels('files'), icon: {text: '\u{1F4C2}'}, onSelect: () => this.showDslFiles()},
-        {id: 'reload', labels: labels('reload'), icon: {text: '↻'}, onSelect: () => this.reloadOpenedDsl()},
-        {id: 'about', labels: labels('about'), icon: {text: 'i'}, onSelect: () => this.showTitle()},
-        {id: 'close', labels: labels('close'), icon: {text: 'x'}, onSelect: () => this.applicationMenu?.hide()}
-      ]
+      actions: this.menuActions.map((action) => ({
+        id: action.id,
+        labels: action.labels,
+        enabled: action.enabled,
+        onSelect: () => this.selectMenuAction(action.id)
+      }))
     });
     return this.applicationMenu;
   }
@@ -241,7 +336,8 @@ export class TurboWarpTitleMenuExtension implements TurboWarpExtension {
           name,
           {
             type: Scratch.ArgumentType[argument.type],
-            defaultValue: argument.defaultValue
+            ...(argument.defaultValue === undefined ? {} : {defaultValue: argument.defaultValue}),
+            ...(argument.menu === undefined ? {} : {menu: argument.menu})
           }
         ])
       )