@ablogcms/plugins 3.2.38 → 3.2.39

package/HOOKS.md

@@ -0,0 +1,1251 @@
+# HOOKS.md — 管理画面 フロントエンド拡張ポイント一覧
+
+a-blog cms 管理画面（React SPA）が提供する フロントエンド側拡張ポイントの一覧。PHP 側の
+`extension/acms/Hook.php`（`ACMS_Hook` が呼ぶ既知メソッド名の雛形）に相当する参照資料であり、
+「今どんな拡張ポイントが存在するか」をここだけ見れば把握できることを目指す。
+
+設計の背景・kintone / WordPress との比較・方針転換の経緯は
+[docs/plan/admin-extensibility-api/design.md](../../../docs/plan/admin-extensibility-api/design.md)、
+受け入れ条件は [requirements.md](../../../docs/plan/admin-extensibility-api/requirements.md) を参照。
+本書はそれらの実装結果を「一覧」として引く用途に絞り、設計判断の理由（Why）は繰り返さない。
+
+## この文書の置き場所について
+
+`docs/foundation/` は基本設計が変わらない限り更新しない恒久ドキュメント、`docs/steering/` は作業単位の
+一時ドキュメントと役割が決まっている（[AGENTS.md](../../../AGENTS.md)）。拡張ポイント一覧は今後の機能追加
+のたびに項目が増減する「コードに従属する参照資料」であり、恒久でも作業単位でもないため、どちらにも
+馴染まない。PHP 側の `Hook.php` 雛形がコア（`ablogcms/extension/acms/`）に同居し `docs/` に置かれていないのと
+対称に、JS 側の雛形に相当する本書も `docs/` の外、拡張の「玄関」である `@ablogcms/plugins`
+（`setup(ctx)` がイベント・レジストリ・UI 差し込みをすべて束ねるパッケージ）直下に置く。
+新しい拡張ポイントを追加した PR は、対応する `AcmsEventMap` 宣言と合わせて本書を更新すること
+（[AGENTS.md](../../../AGENTS.md)「拡張ポイント（フック）の方針」参照）。
+
+## 目次
+
+- [命名規約](#命名規約)
+- [イベント一覧（実行できる操作の対応表）](#イベント一覧実行できる操作の対応表)
+- [登録タイミング制約](#登録タイミング制約)
+- [失敗時の扱い（横断表）](#失敗時の扱い横断表)
+- [Slot 一覧](#slot-一覧)
+- [レジストリ一覧](#レジストリ一覧)
+- [既存の購読可能イベント（DOM CustomEvent・レガシー名前空間）](#既存の購読可能イベントdom-customeventレガシー名前空間)
+- [レガシー API の非推奨一覧と移行例](#レガシー-api-の非推奨一覧と移行例)
+- [`ctx.config` の制約](#ctxconfig-の制約)
+- [`ctx.ui.fill` で fillProps を受け取る（withFillProps）](#ctxuifill-で-fillprops-を受け取るwithfillprops)
+- [プラグイン側のビルド設定（React / Tiptap の共有）](#プラグイン側のビルド設定react--tiptap-の共有)
+- [新しい拡張ポイントを追加するときのルール](#新しい拡張ポイントを追加するときのルール)
+- [ユースケース実装例: メディア alt の AI 生成ボタン](#ユースケース実装例-メディア-alt-の-ai-生成ボタン)
+- [カスタムブロックの作り方](#カスタムブロックの作り方)
+- [ブロックツールバーの拡張](#ブロックツールバーの拡張)
+- [カスタムユニットの作り方](#カスタムユニットの作り方)
+
+## 命名規約
+
+```
+{domain}.{action}.{phase}   例: media.upload.before / media.upload.success
+```
+
+- `domain`・各セグメントは kebab-case（`media` / `unit-editor` / `dataview` 等）。`features/*` の
+  機能ディレクトリ名に揃える。この規約はイベント名・Slot 名・レジストリの登録名すべてに適用される。
+- action が複合語になる場合も kebab-case で 1 セグメントに収める（例:
+  `unit-editor.inplace-dialog-open.after`）。セグメント数は常に 3。
+- `phase` は次の 6 種。**ゲート判定（キャンセル・値変更・非同期待機が効くかどうか）はイベント名の
+  文字列パターンでは決まらない**。`AcmsEventMap` にそのイベントを `AcmsGateEvent<P>` /
+  `AcmsNotifyEvent<P>` のどちらで宣言したかだけで決まり、対応して `ACMS.events.gate(...)` /
+  `ACMS.events.notify(...)` のどちらで発火するかが型レベルで強制される（`.before` で終わる名前は
+  「ゲートらしい」ことを示す可読性のためのドキュメント的な取り決めであり、`unit-editor.command.before`
+  のように名前が `.before` でも通知として宣言されているイベントもある。下記表・注記参照）。
+
+  | phase | 意味 | ゲート? | 例 |
+  |---|---|---|---|
+  | `.before` | 処理の直前。キャンセル・値変更・直列 await が効く | ゲート | `media.upload.before`（実在） |
+  | `.success` | 対応する `.before` ゲートがある処理の正常完了後（API 呼び出し等、失敗しうる非同期処理） | 通知 | `media.upload.success`（実在） |
+  | `.failure` | 処理の失敗後（API エラー等） | 通知 | `validator.submit.failure`（命名例。未実装） |
+  | `.change` | 監視対象の値・選択状態が更新されたことの通知 | 通知 | `category.select.change`（実在） |
+  | `.after` | 対応する `.before` ゲートを持たない UI 操作が完了した直後の通知。例外的な失敗を除き必ず完了する（成功/失敗の分岐がそもそも無い）操作向け | 通知 | `dialog.open.after`（実在） |
+  | `.ready` | 特定の初期化が一度きり完了したことの通知。`on()` の素の再生されない購読ではなく、必ず `ACMS.readyState` 等のプロパティで発火済みかどうかを先に確認してから購読する（「起動系イベント」節参照） | 通知 | `acms.state.ready`（実在） |
+
+  `.success` と `.after` はどちらも「処理が完了した」通知だが、区別の基準は**対応する `.before`
+  ゲートの有無**（＝失敗して分岐しうる処理かどうか）であって、実装上の確実性の高さではない。
+  `.change` と `.after` はどちらも成功/失敗の概念が無い点で共通するが、`.change` は「値が
+  新しくなった」ことを、`.after` は「値の話ではなく操作そのものが完了した」ことを表す
+  （迷った場合の目安: ペイロードに「新しい値」を持つなら `.change`、要素の参照や作成物のような
+  「完了の証跡」しか持たないなら `.after`）。
+
+- ハブのイベント名に `acms.` プレフィックスは付けない（ハブ自体が名前空間）。既存の DOM CustomEvent
+  （`acms.media-updated` 等）とは名前空間が別。
+- Slot 名は `{domain}.{場所}`（phase なし）の慣例。場所が複合する場合は 3 セグメントも可
+  （例: `media.edit-modal.footer`）。
+
+## イベント一覧（実行できる操作の対応表）
+
+`ACMS.events`（`@ablogcms/events`）に登録済みのイベント。「通知（`notify()`）」と「ゲート（`gate()`）」を
+別々のメソッドで表現する。ゲートは `ctx.cancel(reason?)`（キャンセル）・ペイロードの直接書き換え
+（値変更・waterfall）・ハンドラの Promise 待機（非同期ゲート）に対応し、通知は戻り値・`ctx` の
+どちらも持たず購読するだけの一方通行になる（DOM の `Event.cancelable` + `preventDefault()` と同型）。
+
+| イベント名 | 種別 | 通知 | 値変更 | キャンセル | async | ペイロード型（`AcmsEventMap`） | 発火箇所 |
+|---|---|---|---|---|---|---|---|
+| `media.upload.before` | ゲート (`AcmsGateEvent`) | - | △（`payload.files` の**絞り込みのみ**可。差し替え不可。下記注記参照） | ○（`ctx.cancel(reason?)` を呼ぶ） | ○（Promise を返すと待つ） | `{ files: File[] }` | `packages/frontend/media/src/components/media-uploader/media-uploader.tsx` の `uploadItems()` 入口 |
+| `media.upload.success` | 通知 (`AcmsNotifyEvent`) | ○ | ×（型で拒否） | ×（型で拒否） | ×（戻り値は無視。ハンドラ内で await すること自体は可） | `Readonly<{ items: MediaItem[] }>` | 同ファイル、`runWithConcurrency` 完了直後 |
+| `media.update.before` | ゲート (`AcmsGateEvent`) | - | ○（`payload.formData` を直接書き換える） | ○（`ctx.cancel(reason?)` を呼ぶ） | ○（Promise を返すと待つ） | `{ item: MediaItem; formData: FormData }` | `packages/frontend/media/src/components/media-modal/media-modal.tsx` の `update()` 冒頭（`buildFormData` 後、既存のファイル変更確認 `confirm()` の後）。ユーザーが `confirm()` をキャンセルした場合はこのゲート自体が発火しない |
+| `media.update.success` | 通知 (`AcmsNotifyEvent`) | ○ | ×（型で拒否） | ×（型で拒否） | ×（戻り値は無視） | `Readonly<{ item: MediaItem }>` | 同ファイル、保存成功直後。既存の DOM CustomEvent `acms.media-updated` と二重発火する（新バス → レガシーの順。決定事項「レガシーとの併走方針」） |
+| `media.update-as-new.before` | ゲート (`AcmsGateEvent`) | - | ○（`payload.formData` を直接書き換える） | ○（`ctx.cancel(reason?)` を呼ぶ） | ○（Promise を返すと待つ） | `{ item: MediaItem; formData: FormData }` | 同ファイル、`uploadAsNew()` 冒頭（`buildFormData` 後） |
+| `media.update-as-new.success` | 通知 (`AcmsNotifyEvent`) | ○ | ×（型で拒否） | ×（型で拒否） | ×（戻り値は無視） | `Readonly<{ item: MediaItem }>` | 同ファイル、別名保存成功直後。別名保存はレガシー DOM イベント（`acms.media-updated`）を飛ばさないため、二重発火はない |
+| `media.delete.before` | ゲート (`AcmsGateEvent`) | - | △（`payload.mediaIds` の差し替えは後続ハンドラ・`.success` 通知には伝わるが、実際の削除対象はチェック状態から構築される FormData に基づくため絞り込みには反映されない。除外したい場合は cancel で一括拒否する） | ○（`ctx.cancel(reason?)` を呼ぶ） | ○（Promise を返すと待つ） | `{ mediaIds: string[] }`（`mediaIds` はチェックボックスが実際に描画されるアイテムのみを数える。`mode==='edit'` かつ `media_editable` が false の行はチェックボックス自体が無いため対象外） | `packages/frontend/media/src/components/media-list/media-list.tsx` の `removeImgs()` 冒頭（確認ダイアログ通過後） |
+| `media.delete.success` | 通知 (`AcmsNotifyEvent`) | ○ | ×（型で拒否） | ×（型で拒否） | ×（戻り値は無視） | `Readonly<{ mediaIds: string[] }>` | 同ファイル、一括削除成功直後 |
+| `entry.trash.before` | ゲート (`AcmsGateEvent`) | - | ○（`payload.entry` を直接書き換えると、その差し替え後のエントリーが実際の削除対象になる。`entry.trash.success` の通知ペイロードにも反映される） | ○（`ctx.cancel(reason?)` を呼ぶ） | ○（Promise を返すと待つ） | `{ entry: RowData }`（`RowData` は行の型を消去した `@ablogcms/components/dataview/types` の型。実体は `EntryType`） | `ablogcms/js/src/features/entry/hooks/use-entry-admin-actions.tsx` の trash アクション、`window.confirm` 通過後 |
+| `entry.trash.success` | 通知 (`AcmsNotifyEvent`) | ○ | ×（型で拒否） | ×（型で拒否） | ×（戻り値は無視） | `Readonly<{ entry: RowData }>` | 同ファイル、trashEntry 成功直後 |
+| `entry.duplicate.success` | 通知 (`AcmsNotifyEvent`) | ○ | ×（型で拒否） | ×（型で拒否） | ×（戻り値は無視） | `Readonly<{ entry: RowData }>` | 同ファイル、duplicate アクション。確認ダイアログが無い操作のため before ゲートは設けない |
+| `entry.bulk-status.before` | ゲート (`AcmsGateEvent`) | - | ○（`payload.formData` を直接書き換える） | ○（`ctx.cancel(reason?)` を呼ぶ） | ○（Promise を返すと待つ） | `{ formData: FormData }` | `use-entry-admin-bulk-actions.tsx` の status 一括アクション冒頭。公開/非公開切替の割り込み点として最有用 |
+| `entry.bulk-status.success` | 通知 (`AcmsNotifyEvent`) | ○ | ×（型で拒否） | ×（型で拒否） | ×（戻り値は無視） | `Readonly<{ formData: FormData }>` | 同ファイル、bulkChangeStatus 成功直後 |
+| `entry.bulk-trash.success` | 通知 (`AcmsNotifyEvent`) | ○ | ×（型で拒否） | ×（型で拒否） | ×（戻り値は無視） | `Readonly<{ formData: FormData }>` | 同ファイル、trash 一括アクション成功直後 |
+| `entry.bulk-duplicate.success` | 通知 (`AcmsNotifyEvent`) | ○ | ×（型で拒否） | ×（型で拒否） | ×（戻り値は無視） | `Readonly<{ formData: FormData }>` | 同ファイル、duplicate 一括アクション成功直後 |
+| `module.bulk-status.before` | ゲート (`AcmsGateEvent`) | - | ○（`payload.formData` を直接書き換える） | ○（`ctx.cancel(reason?)` を呼ぶ） | ○（Promise を返すと待つ） | `{ formData: FormData }` | `ablogcms/js/src/features/module/hooks/use-module-admin-bulk-actions.tsx` の status 一括アクション冒頭。entry 側 `entry.bulk-status.*` と同型の横展開 |
+| `module.bulk-status.success` | 通知 (`AcmsNotifyEvent`) | ○ | ×（型で拒否） | ×（型で拒否） | ×（戻り値は無視） | `Readonly<{ formData: FormData }>` | 同ファイル、bulkChangeStatus 成功直後 |
+| `preview.share.before` | ゲート (`AcmsGateEvent`) | - | ○（`payload.formData` を直接書き換える） | ○（`ctx.cancel(reason?)` を呼ぶ） | ○（Promise を返すと待つ） | `{ formData: FormData }` | `ablogcms/js/src/features/preview/hooks/use-share-preview.ts` の `createPreviewShareUrl` 実行直前。**発火元がガード付き**（`ACMS.events?.gate(...)`。後述） |
+| `preview.share.success` | 通知 (`AcmsNotifyEvent`) | ○ | ×（型で拒否） | ×（型で拒否） | ×（戻り値は無視） | `Readonly<{ shareUrl: string }>` | 同ファイル、共有 URL 発行成功直後。同上ガード付き |
+| `preview.mode.change` | 通知 (`AcmsNotifyEvent`) | ○ | ×（型で拒否） | ×（型で拒否） | ×（戻り値は無視） | `Readonly<{ enabled: boolean }>` | `use-preview-mode.ts` の enable/disable 両方。**発火元がガード付き**（`ACMS.events?.notify(...)`）。プレビュー共有ページ（`admin/preview/share.html`）は `Preview::isPreviewShareAdmin` により管理画面バンドル（`ACMS.events` を初期化する `admin.js`）が読み込まれず、公開エントリの `built-in/dispatch.js`（`ACMS.Dispatch.Preview`）経由でこのフックへ到達しうるため、`ACMS.events` が未定義の可能性がある |
+| `timemachine.mode.change` | 通知 (`AcmsNotifyEvent`) | ○ | ×（型で拒否） | ×（型で拒否） | ×（戻り値は無視） | `Readonly<{ enabled: boolean }>` | `timemachine-modal.tsx` の enable/disable 両方。`preview.mode.change` と同型の横展開 |
+| `category.select.change` | 通知 (`AcmsNotifyEvent`) | ○ | ×（型で拒否） | ×（型で拒否） | ×（戻り値は無視） | `Readonly<{ target: HTMLElement }>` | `ablogcms/js/src/features/category/mount-category-select.tsx`。DOM CustomEvent `acms.category.change` と二重発火（新バス→レガシーの順）。バス化により全インスタンスに届くため `target` でフィルタすること |
+| `sub-category.select.change` | 通知 (`AcmsNotifyEvent`) | ○ | ×（型で拒否） | ×（型で拒否） | ×（戻り値は無視） | `Readonly<{ target: HTMLElement }>` | `ablogcms/js/src/features/sub-category/mount-sub-category-select.tsx`。DOM CustomEvent `acms.sub-category.change` と二重発火。`target` フィルタ注意は上記と同様 |
+| `tag.select.change` | 通知 (`AcmsNotifyEvent`) | ○ | ×（型で拒否） | ×（型で拒否） | ×（戻り値は無視） | `Readonly<{ target: HTMLElement }>` | `ablogcms/js/src/features/tag/mount-tag-select.tsx`。DOM CustomEvent `acms.tag.change` と二重発火。`target` フィルタ注意は上記と同様 |
+| `related-entry.select.change` | 通知 (`AcmsNotifyEvent`) | ○ | ×（型で拒否） | ×（型で拒否） | ×（戻り値は無視） | `Readonly<{ target: HTMLElement; entries: unknown[]; type: string; title: string; moduleId: string; ctx: string; maxItem: number }>` | `ablogcms/js/src/features/related-entry/mount-related-entry.tsx`。DOM CustomEvent `acms.related-entry.change` と二重発火。`target` フィルタ注意は上記と同様 |
+| `entry.main-image.change` | 通知 (`AcmsNotifyEvent`) | ○ | ×（型で拒否） | ×（型で拒否） | ×（戻り値は無視） | `Readonly<{ target: HTMLElement; mediaId: number \| string \| null; thumbnail: string }>` | `packages/frontend/block-editor/src/extensions/ImageBlock/components/ImageBlockMenuSection.tsx`（BlockMenu 統合で `ImageBlockMenu.tsx` から抽出された側。旧ファイルは deprecated ラッパーで発火を持たない）。DOM CustomEvent `acms.set-main-image` と二重発火。レガシー側の `detail.media_type`（常に固定値 `'image'`。ImageBlock 専用の発火経路のため）は新バス側では意図的に省略している |
+| `media-field.change` | 通知 (`AcmsNotifyEvent`) | ○ | ×（型で拒否） | ×（型で拒否） | ×（戻り値は無視） | `Readonly<{ target: HTMLElement }>` | `ablogcms/js/src/dispatch/media/dispatch-media-field.tsx`（4 箇所）。DOM CustomEvent `acms.media-field.change` と二重発火（自社購読なし・ミラーのみ） |
+| `media-unit.change` | 通知 (`AcmsNotifyEvent`) | ○ | ×（型で拒否） | ×（型で拒否） | ×（戻り値は無視） | `Readonly<{ target: HTMLElement; mediaItems: MediaItem[] }>` | `packages/frontend/media/src/setup-media-unit.tsx`。DOM CustomEvent `acms.media-unit.change` と二重発火（自社購読なし・ミラーのみ） |
+| `admin.delayed-contents.change` | 通知 (`AcmsNotifyEvent`) | ○ | ×（型で拒否） | ×（型で拒否） | ×（戻り値は無視） | `Readonly<{ target: EventTarget; detail: unknown }>` | `ablogcms/js/src/admin.js` の中継ブロック（4 箇所）。レガシー `acmsAdminDelayedContents` と二重発火 |
+| `custom-field-maker.preview.after` | 通知 (`AcmsNotifyEvent`) | ○ | ×（型で拒否） | ×（型で拒否） | ×（戻り値は無視） | `Readonly<{ element: HTMLElement }>` | `ablogcms/js/src/admin.js` の中継ブロック（1 箇所）。発火元は npm 依存 `custom-field-maker`（v1.6.8）側のレガシー `acmsCustomFieldMakerPreview`（`window.ACMS.dispatchEvent` 経由）。購読側 4 箇所（a-table field / rich editor / lite editor field / media field の各再初期化）はこの新バスイベントに移行済み。custom-field-maker 自体が将来 `window.ACMS.events.notify(...)` を直接呼ぶようになれば中継ブロックは不要になる |
+| `dialog.open.after` | 通知 (`AcmsNotifyEvent`) | ○ | ×（型で拒否） | ×（型で拒否） | ×（戻り値は無視） | `Readonly<{ element: HTMLElement }>` | ダイアログ/モーダル/ドロワーの発火箇所計 8 箇所。レガシー `acmsDialogOpened` と二重発火 |
+| `field-group.add.after` | 通知 (`AcmsNotifyEvent`) | ○ | ×（型で拒否） | ×（型で拒否） | ×（戻り値は無視） | `Readonly<{ element: HTMLElement }>` | `ablogcms/js/dispatch.js:1145`。レガシー `acmsAddCustomFieldGroup` と二重発火。購読は `ablogcms/js/src/built-in/dispatch.js` の wysiwyg/flatpicker 初期化 2 箇所が `on(...)` 経由に移行済み |
+| `tab.select.change` | 通知 (`AcmsNotifyEvent`) | ○ | ×（型で拒否） | ×（型で拒否） | ×（戻り値は無視） | `Readonly<{ tab: HTMLElement }>` | `ablogcms/js/dispatch/admin.js`。レガシー `acmsAdminSelectTab` と二重発火 |
+| `tab.show.after` | 通知 (`AcmsNotifyEvent`) | ○ | ×（型で拒否） | ×（型で拒否） | ×（戻り値は無視） | `Readonly<{ tab: HTMLElement; panel: HTMLElement \| null }>` | `ablogcms/js/dispatch/admin.js` / `packages/frontend/unit-editor/src/hooks/use-tab.ts`。レガシー `acmsAdminShowTabPanel` と二重発火 |
+| `tab.hide.after` | 通知 (`AcmsNotifyEvent`) | ○ | ×（型で拒否） | ×（型で拒否） | ×（戻り値は無視） | `Readonly<{ tab: HTMLElement; panel: HTMLElement \| null }>` | 同上。レガシー `acmsAdminHideTabPanel` と二重発火 |
+| `geo.info-add.after` | 通知 (`AcmsNotifyEvent`) | ○ | ×（型で拒否） | ×（型で拒否） | ×（戻り値は無視） | `Readonly<{ element: HTMLElement }>` | `ablogcms/js/src/admin.js`（地図ピッカー）。レガシー `onGeoInfoAdded` と二重発火 |
+| `lazy-load.load.after` | 通知 (`AcmsNotifyEvent`) | ○ | ×（型で拒否） | ×（型で拒否） | ×（戻り値は無視） | `Readonly<{ element: HTMLElement }>` | `ablogcms/js/config.js` の `lazyLoadConfig.loaded`。レガシー `acmsLazyLoaded` と二重発火 |
+| `validator.invalid.after` | 通知 (`AcmsNotifyEvent`) | ○ | ×（型で拒否） | ×（型で拒否） | ×（戻り値は無視） | `Readonly<{ results: ValidationResult[]; element: HTMLElement }>` | `ablogcms/js/config.js` の `validatorOptions.onInvalid`。レガシー `acmsFormInvalid` と二重発火 |
+| `validator.valid.after` | 通知 (`AcmsNotifyEvent`) | ○ | ×（型で拒否） | ×（型で拒否） | ×（戻り値は無視） | `Readonly<{ results: ValidationResult[]; element: HTMLElement }>` | 同ファイルの `onValid`。レガシー `acmsFormValid` と二重発火 |
+| `validator.validated.after` | 通知 (`AcmsNotifyEvent`) | ○ | ×（型で拒否） | ×（型で拒否） | ×（戻り値は無視） | `Readonly<{ results: ValidationResult[]; element: HTMLElement }>` | 同ファイルの `onValidated`。レガシー `acmsFormValidated` と二重発火 |
+| `validator.submit-fail.after` | 通知 (`AcmsNotifyEvent`) | ○ | ×（型で拒否） | ×（型で拒否） | ×（戻り値は無視） | `Readonly<{ results: ValidationResult[]; form: HTMLFormElement }>` | 同ファイルの `onSubmitFailed`。レガシー `acmsValidateFailed` と二重発火 |
+| `unit-editor.inplace-dialog-open.after` | 通知 (`AcmsNotifyEvent`) | ○ | ×（型で拒否） | ×（型で拒否） | ×（戻り値は無視） | `Readonly<{ element: HTMLElement }>` | `ablogcms/js/dispatch/edit/_inplace.js:548`（レガシー jQuery 領域）。レガシー `acmsInplaceDialogOpen` と二重発火 |
+| `unit-editor.create.after` | 通知 (`AcmsNotifyEvent`) | ○ | ×（型で拒否） | ×（型で拒否） | ×（戻り値は無視） | `Readonly<{ editor: Editor; settings: UnitEditorSettings }>` | `packages/frontend/unit-editor/src/components/unit-editor/index.tsx`。レガシー `acmsUnitEditorCreate` と二重発火（テーマ側が購読する公開仕様のためレガシー側も維持） |
+| `unit-editor.command.before` | 通知 (`AcmsNotifyEvent`)。命名は `.before` だが観測専用（下記注記参照） | ○ | ×（型で拒否） | ×（型で拒否） | ×（戻り値は無視） | `Readonly<{ commands: string[]; editor: Editor }>` | `packages/frontend/unit-editor/src/core/command-manager.ts` はエディタ自身の内部イベント（`editor.emit('beforeTransaction'/'transaction', ...)`）のみを発火し、グローバルバスは直接呼ばない。実際の発火は、エディターを使う側の 3 箇所（`unit-editor` / `inplace-editor` コンポーネント、`use-config-editor` フック）が `onBeforeTransaction` オプション経由で `emit-command-events.ts` の `emitCommandBefore` を呼ぶ形（`unit-editor.create.after` 等、既存の `onCreate` 系オプションと同じパターン）。ユニットの追加/削除/移動/複製/更新など全コマンド共通。`commands.xxx()` / `chain().run()` は package 内 60 箇所以上から同期呼び出しされており、真にキャンセル可能にするには全呼び出し元を async 化する必要があるため、影響範囲・回帰リスクの大きさからゲート化は見送り、`AcmsEventMap` でも通知（`AcmsNotifyEvent`）として宣言している。命名の `.before` は「他のコマンド発火順序と合わせた慣習」であり、ゲート/通知の判定要因ではない（判定は `AcmsEventMap` の宣言そのもの。命名規約は可読性のためのドキュメント的な取り決めに過ぎない） |
+| `unit-editor.command.success` | 通知 (`AcmsNotifyEvent`) | ○ | ×（型で拒否） | ×（型で拒否） | ×（戻り値は無視） | `Readonly<{ commands: string[]; editor: Editor }>` | 同上。`onTransaction` オプション経由で `emitCommandSuccess` を呼ぶ |
+
+- ペイロード型の宣言（module augmentation）は機能ごとの `events.ts` に置く（media ドメインは
+  `packages/frontend/media/src/events.ts`、unit-editor パッケージ内で発火するものは
+  `packages/frontend/unit-editor/src/events.ts`、特定の機能パッケージを持たない管理画面コア/
+  レガシー系は `packages/frontend/lib/src/events.ts`、entry/module admin のライフサイクル操作は
+  `packages/frontend/plugins/src/events.ts` に集約）。
+  Why not（アプリ側 `ablogcms/js/src/` 配下に置かない理由）: 実測で、アプリ側のファイルから
+  `declare module '@ablogcms/events'` で `AcmsEventMap` を拡張すると、他パッケージ側の
+  `AcmsEventOf<K>` 解決が `AcmsLooseEvent` に落ちるビルド不整合が発生したため（コメント記法や
+  型の複雑さとは無関係に単一の空エントリでも再現する）、この種の宣言は `packages/frontend/*/src`
+  配下に統一して置く（詳細は `packages/frontend/lib/src/events.ts` のコメント参照）。
+  `EntryType`/`ModuleType` のようなアプリ側専用の型はパッケージ側から参照できないため、
+  `packages/frontend/plugins/src/events.ts` では行の型を消去した `RowData`
+  （`@ablogcms/components/dataview/types`。`ctx.dataview.registerAction` 等と同じ型）で宣言し、
+  消費側の feature が実際の型へキャストする（`packages/frontend/plugins/src/events.ts` のコメント参照）。
+- `AcmsGateEvent<P>` / `AcmsNotifyEvent<P>`（`packages/frontend/events/src/core/types.ts`）は
+  `{ kind: 'gate'; payload: P }` / `{ kind: 'notify'; payload: Readonly<P> }` の判別可能なユニオン型。
+  `AcmsEventMap` にどちらで宣言されているかによって、`ACMS.events.gate(type, ...)` /
+  `ACMS.events.notify(type, ...)` のうち呼べる方がコンパイル時に決まる（宣言と異なるメソッドで呼ぶと
+  型エラーになる）。ゲートハンドラは `(payload, ctx)` の2引数、通知ハンドラは `(payload)` の1引数のみを
+  受け取る（`NotifyHandler<K>` / `GateHandler<K>`）。**通知ハンドラの型に `ctx`（キャンセル手段）は
+  そもそも存在しない**ため、通知のつもりで登録したハンドラが誤ってキャンセルしてしまう事故が型レベルで
+  起きない。
+- 未宣言のイベント名（プラグイン独自イベント）は `Record<string, unknown>` 相当の緩い型
+  （`AcmsLooseEvent`）で使え、コンパイルエラーにはならない。`gate()`/`notify()` のどちらでも呼べる
+  （種別不明のため相互運用性を優先）。
+- **キャンセルは `ctx.cancel(reason?)` を呼んだ瞬間に効果を持つ**（DOM の `event.preventDefault()` と
+  同じ発想。戻り値でキャンセルを表現する旧方式は廃止した。`return false;` は jQuery のイベントハンドラで
+  「デフォルト動作の抑止」を意味する定番のイディオムであり、既存コードは jQuery と併走しているため、
+  戻り値ベースのキャンセルは「他の目的で書いた `return false;` が意図せずゲートをキャンセルさせる」
+  事故と隣り合わせだった。`ctx.cancel(reason?)` は明示的なメソッド呼び出しのため、`return` を挟まず
+  呼んだ時点で確定する）:
+  ```ts
+  ACMS.events.on('media.upload.before', async (payload, ctx) => {
+    if (!(await isAllowed(payload.files))) {
+      ctx.cancel('この操作は許可されていません'); // 理由ありキャンセル。return は不要
+      return;
+    }
+    if (payload.files.length === 0) {
+      ctx.cancel(); // 理由なしキャンセル
+      return;
+    }
+    payload.files = payload.files.filter((f) => f.size < LIMIT); // 値変更（waterfall。フィールドを直接書き換える）
+  });
+  ```
+  - `gate()` の戻り値 `GateResult<P>` は `reason?: string`（ビジネスキャンセルの理由。`ctx.cancel(reason)`
+    経由でのみ入る）と `error?: unknown`（ハンドラが throw / reject した場合の生例外。異常中断）を
+    分離して持つ。
+    ```ts
+    const result = await ACMS.events.gate('media.upload.before', { files });
+    if (result.canceled) {
+      if (result.reason) notify.error(result.reason); // ビジネスキャンセル → ユーザーに理由を表示
+      // result.error があれば異常中断（console にはバス側が記録済み）
+      return;
+    }
+    // result.payload には waterfall 後の最終ペイロードが入る
+    ```
+- **`media.upload.before` は絞り込み専用（除外のみ可・差し替え不可）**: ハンドラが差し替えた `payload.files`
+  は `Set<File>` の参照一致でのみフィルタされるため、ハンドラが新しい `File` インスタンスを生成して
+  差し替えても反映されない。既存ファイルを間引く用途にのみ使うこと。
+- パイプライン仕様（`packages/frontend/events/src/core/create-event-bus.ts` に実装・テスト済み）:
+  - ハンドラは**登録順に逐次実行**（`for...of` + `await`）。並列実行はしない。
+  - ゲートはペイロードを共有参照として全ハンドラに渡す。ハンドラがフィールドを直接書き換えると
+    次のハンドラ・最終的な `result.payload` にその変更が反映される（waterfall）。
+  - `ctx.cancel(reason?)` の呼び出し・throw / reject のいずれかで**残りのハンドラをスキップ**し、
+    `{ canceled: true, reason?, error?, payload }` を返す。throw/reject は `console.error` にハンドラ名
+    付きで記録したうえでキャンセル扱いにする（`error` に生例外が入る）。
+  - 通知イベントはハンドラの戻り値を無視する（そもそも `ctx` を受け取らないためキャンセル自体ができない）。
+    ハンドラの例外はそのハンドラだけを分離してログし、他のハンドラ・コアの動作は継続する。
+  - `priority` や `namespace` の概念はない。実行順は登録順のみ（PHP Hook・Vite/Rollup と同じ設計）。
+- コア側の発火は `await ACMS.events.gate(type, payload)` / `await ACMS.events.notify(type, payload)`。
+  プラグイン側からの呼び出しはコア専用 API という位置づけだが、独自イベントを自分で発火すること自体は
+  禁止しない。
+- 開発モード（`NODE_ENV !== 'production'`）限定の警告 2 種:
+  - 一度でも発火済みのイベント名への遅延購読 → `console.warn`（eventPool のような後追い再生はしない
+    仕様の裏返し。過去の発火は再生されず、以後の発火にのみ反応する）。
+  - ゲートハンドラの所要時間が閾値（既定 3000ms）を超えた場合 → `console.warn`
+    （強制打ち切りはしない。VS Code の `waitUntil` バジェットのような硬い制約は未導入）。
+
+## 登録タイミング制約
+
+- ハンドラ登録・レジストリ登録・`ctx.ui.fill` はすべて**スクリプト読み込み時にトップレベルで同期的に**
+  行うこと。`DOMContentLoaded` 待ちや非同期コールバック内での登録は不可（kintone と同じ運用ルール）。
+- プラグイン JS は **`<script type="module">`（または `defer`）で読み込むこと**。HTML 仕様上 DOM 解析完了後・
+  `DOMContentLoaded` 前に出現順で同期実行されるため、「プラグインの登録 → core の消費（`notify`/`gate` /
+  レジストリ読み出し）」の順序が構造的に保証される。
+- **`InjectTemplate` の登録順 = `<script>` の出力順 = ハンドラ登録順**。複数プラグインの実行順を
+  `InjectTemplate::add()` の呼び出し順（＝ ServiceProvider の初期化順）で制御できる（kintone がプラグイン間
+  順序を保証していない弱点を仕様で塞ぐ）。
+- `ACMS.events` / `ACMS.plugins` は `admin.js` の初期化時に生成される（型定義は `@ablogcms/events/acms` /
+  `@ablogcms/plugins/acms` が `@ablogcms/types/acms` の `Acms` へ追記する `events` / `plugins`
+  プロパティ参照。registry パターンの詳細は [PACKAGING.md](../PACKAGING.md) 参照）。これより前に
+  読み込まれたスクリプトからは `window.ACMS.events` 等が undefined になる。
+
+## 失敗時の扱い（横断表）
+
+拡張点ごとに「登録・宣言が不正だったとき」「実行時に例外が出たとき」の扱いが異なる。個々の判断には
+理由があるが、プラグイン作者が 1 箇所で見比べられるようここにまとめる。
+
+| 場面 | 挙動 | 実装 |
+|---|---|---|
+| レジストリへ同じ `name` を二重登録（`registerUnitDefinition` / `registerColumnType` / `registerBlockDefinition` / `registerExtension` / dataview 系） | **例外を投げる**（`[@ablogcms/plugins] {label} "{name}" は既に登録されています。`）。警告に留めない strict 方針 | `packages/frontend/plugins/src/core/create-registry.ts` |
+| `registerBlockDefinition` / `registerExtension` のファクトリが例外を投げた | **そのエントリだけスキップ**し `console.error`。他のプラグイン・エディター本体は動き続ける | `ablogcms/js/src/features/block-editor/block-definitions.ts` |
+| 拡張内 `blockMenu` 宣言が不正（配列でない・データ型/コンポーネント型のどちらの形にも一致しない・`scope` が未知） | **その項目だけ無視**し `console.warn`（拡張名付き）。例外は投げない | `packages/frontend/block-editor/src/components/menus/BlockMenu/collectBlockMenuItems.ts` |
+| 同じ Slot に同じ id の Fill を再登録（`ctx.ui.fill` は プラグイン名 + 連番で id を採番） | **同じ位置で差し替え**（upsert）。エラーにはしない | `packages/frontend/components/src/slot-fill/slot-fill-store.ts` |
+| ゲートハンドラが throw / reject | そのゲートは**キャンセル扱い**（`result.error` に生例外）。バス側が `console` に記録する | `packages/frontend/events/src/core/create-event-bus.ts` |
+| 通知ハンドラが throw | **そのハンドラだけ分離**してログし、他のハンドラ・コアの動作は継続 | 同上 |
+
+「重複登録は例外／宣言の不正は警告」という粒度の違いは意図的なもので、前者は**起動時に必ず気づける
+設定ミス**、後者は**1 項目を落としてもエディターを使い続けられる実行時データ**という区別による。
+
+## Slot 一覧
+
+`Slot`/`Fill`（`@ablogcms/components/slot-fill`）は UI 差し込み位置の名前付きレジストリ。既存の
+`@components/slot`（Radix 由来の `asChild` 合成パターン、単一要素へのプロパティ委譲）とは無関係の別物なので
+import パスを混同しないこと（`@components/slot` vs `@ablogcms/components/slot-fill`）。
+
+| Slot 名 | 場所 | `fillProps` の型 | 備考 |
+|---|---|---|---|
+| `unit-editor.unit-toolbar` | `packages/frontend/unit-editor/src/components/unit-toolbar/presets/common-toolbar.tsx`（`CommonUnitToolbar`） | `UnitToolbarSlotFillProps`（`{ editor: Editor; unit: UnitTreeNode }`。同ファイルでエクスポート） | 全ユニット共通ツールバーへの独自ボタン/メニュー注入口。`unit-editor` / `inplace-editor` / `config-editor` の 3 つの独立 React ルート（`ablogcms/js/src/features/unit-editor/mount-unit-{editor,inplace-editor,config-editor}.tsx`）がそれぞれ `SlotFillProvider`（グローバル Fill ブリッジ経由）でラップしている |
+| `block-editor.menus` | `packages/frontend/block-editor/src/components/BlockEditor/BlockEditor.tsx`（`BlockEditor`） | `BlockEditorMenusSlotFillProps`（`{ editor: Editor; appendTo: RefObject<HTMLElement \| null> }`。同ファイルでエクスポート） | エディター直下に並ぶ既定メニュー（`ContentItemMenu` / `LinkMenu` / `BlockMenu` / `TableRowMenu` / `TableColumnMenu` の 5 つ）の直後に置かれた追加口。既定メニューの差し替え・削除には対応しない（追加のみ）。`ablogcms/js/src/features/block-editor/mount-block-editor.tsx`（フィールド用スタンドアロン）と unit-editor 経由の 3 ルート（`BlockEditorExtensionsProvider` 配線済み）の両方で有効。スタンドアロン経路は `SlotFillProvider`（グローバル Fill ブリッジ経由）でラップ済み |
+| `block-editor.block-menu` | `packages/frontend/block-editor/src/components/menus/BlockMenu/BlockMenu.tsx`（`BlockMenu`）、共通区画（`BlockCommonSection` の直後） | `BlockMenuSlotFillProps`（`{ editor: Editor; variant: BlockMenuVariant }`。同ファイルでエクスポート） | BlockMenu（統合ブロックツールバー）の共通区画への UI 差し込み口。ブロック種別（`variant`）を問わず常に描画される。UI だけを差し込みたい場合の低レベル経路で、ノード・コマンドを伴う拡張を作るなら「拡張内 `blockMenu` 宣言」（レジストリ一覧の `ctx.blockEditor.registerExtension` 参照）の方がコロケーションの観点で自然。使い分けの詳細は「ブロックツールバーの拡張」節参照 |
+| `block-editor.block-menu.text` | 同上、テキスト系ブロックの種別別区画の末尾（`TextFormatSection` と拡張の `blockMenu` 宣言項目の後） | `BlockMenuSlotFillProps`（`block-editor.block-menu` と同じ型。`variant` は常に `'text'`） | テキスト系ブロック（段落・見出し・引用等）がアクティブなときだけ描画される種別別区画 |
+| `block-editor.block-menu.image` | 同上、画像ブロックの種別別区画の末尾（`ImageBlockMenuSection` と拡張の `blockMenu` 宣言項目の後） | `BlockMenuSlotFillProps`（`variant` は常に `'image'`） | 画像ブロックがアクティブなときだけ描画される種別別区画 |
+| `block-editor.block-menu.file` | 同上、ファイルブロックの種別別区画の末尾（`FileBlockMenuSection` と拡張の `blockMenu` 宣言項目の後） | `BlockMenuSlotFillProps`（`variant` は常に `'file'`） | ファイルブロックがアクティブなときだけ描画される種別別区画 |
+| `block-editor.block-menu.linkButton` | 同上、リンクボタンブロックの種別別区画の末尾（`LinkButtonMenuSection` と拡張の `blockMenu` 宣言項目の後） | `BlockMenuSlotFillProps`（`variant` は常に `'linkButton'`） | リンクボタンブロックがアクティブなときだけ描画される種別別区画 |
+| `block-editor.block-menu.table` | 同上、テーブルの種別別区画の末尾（`TableMenuSection` と拡張の `blockMenu` 宣言項目の後） | `BlockMenuSlotFillProps`（`variant` は常に `'table'`） | テーブル（セル選択）がアクティブなときだけ描画される種別別区画 |
+| `media.edit-modal.field.alt` | `packages/frontend/media/src/components/media-modal/media-modal.tsx`（`MediaModal`）、alt textarea 直後 | `MediaEditModalAltFillProps`（`{ item: MediaItem; previewSrc: string; getAlt(): string; setAlt(v: string): void }`。同ファイルでエクスポート） | メディア詳細モーダルの alt 欄への独自ボタン注入口（AI alt 生成等）。`setAlt` は `AutoResizeTextarea` の `setValue`（imperative handle）経由で内部 state・DOM 値・自動リサイズをまとめて更新する。`ACMS.Config.mediaShowAltAndCaptionOnModal` が off のとき alt 行ごと非表示になり、この Slot も一緒に消える仕様（alt 生成という文脈から離れる置き場所を避けるため行外には置かない）。MediaModal は共有コンポーネントのため、メディア管理・カスタムフィールド・ブロックエディター画像/ファイル・リッチエディター・バナー・ナビゲーション・ユニットの 8 経路すべてに同時に効く |
+| `media.edit-modal.fields` | 同上、編集タブの `</Table>` 直後（`<TableBody>` の外。table の子要素制約により行内には置けない） | `MediaEditModalFieldsFillProps`（`{ item: MediaItem }`。同ファイルでエクスポート） | 独自メタパネルの受け皿。config 非依存で常時表示 |
+| `media.edit-modal.footer` | 同上、保存ボタン後・`</HStack>` 直前 | `MediaEditModalFooterFillProps`（`{ item: MediaItem; getFormData(): FormData }`。同ファイルでエクスポート） | `getFormData()` は `buildFormData('ACMS_POST_Media_Update')` と同じ FormData を組み立てて返す（保存直前の内容を読み取れる）。`item` が null になりうる箇所のため `{item && <Slot ... />}` でガードしている |
+| `media.list.bulk-actions` | `packages/frontend/media/src/components/media-list/media-list.tsx`（`MediaList`）、削除・タグ付与の両分岐の外（常時表示） | `MediaListBulkActionsFillProps`（`{ selectedItems: MediaItem[] }`。同ファイルでエクスポート） | メディア一覧の一括操作エリアへの独自ボタン注入口（一覧は元々拡張口ゼロだった）。`editMode` の値に関わらず常に描画される。`selectedItems` はチェックボックスが実際に描画されるアイテムのみ（`getSelectedItems()`、`media.delete.before` と同じ絞り込み） |
+| `preview.actions` | `ablogcms/js/src/features/preview/components/preview-actions/preview-actions.tsx`（`PreviewActions`）、既存ボタンの後（capture/share のいずれかが有効なときのみ描画） | fillProps なし | プレビューモーダル（`preview-modal.tsx`）とインラインプレビュー（`inline-preview.tsx`）の両方から共有される単一コンポーネントのため、ここに置くだけで両経路に効く。両 dispatcher（`dispatch-preview-mode.tsx` / `dispatch-inline-preview.tsx`）を `renderWithProviders` に切り替えて Slot を有効化した |
+| `unit-editor.top` | `packages/frontend/unit-editor/src/components/unit-editor/index.tsx`（`UnitEditor`）、`EditorContent` 直前 | `UnitEditorSlotFillProps`（`{ editor: Editor }`。同ファイルでエクスポート） | AI 補助バー・テンプレ挿入等の受け皿。`unit-editor` / `inplace-editor` / `config-editor` の 3 ルートは既に `SlotFillProvider` でラップ済み（`unit-editor.unit-toolbar` と同じ配線） |
+| `unit-editor.bottom` | 同上、`EditorContent` 直後 | `UnitEditorSlotFillProps`（`unit-editor.top` と同じ型） | 同上 |
+
+- 同名 Slot に複数の Fill が登録された場合、すべて**登録順に描画**される。
+- `Fill` の `children` は通常の `ReactNode`、または `(fillProps) => ReactNode` の render-prop 形式の
+  どちらも渡せる（`FillRenderer<T>`）。`<Fill>` を JSX で直接書く場合はどちらの形式も渡せる。
+  `ctx.ui.fill()` 経由の登録から render-prop 形式（fillProps を受け取る形）を使いたい場合は
+  `withFillProps` でラップする（下記「`ctx.ui.fill` で fillProps を受け取る（withFillProps）」参照）。
+- DOM コールバック Fill（`(el: HTMLElement) => void | (() => void)`）は `DomFillMount`
+  （`@ablogcms/components/slot-fill`）が空の `div` を描画し ref で `el` を払い出すことで実現している。
+  `el` の中身は React の reconcile 対象にならない（JSX 上 `children` を持たないため、命令的に追加した
+  DOM を再レンダーで消したり書き換えたりしない）。戻り値（クリーンアップ関数）はアンマウント時に呼ばれる。
+- React コンポーネント（props なし）か `DomFill` かの判別は実行時の**仮引数の個数**
+  （`Function.prototype.length`）で行う（`packages/frontend/plugins/src/core/resolve-fill-entry.ts`）:
+  0 個 = 引数なしの React コンポーネント、1 個以上 = `DomFill`。**props を要求する関数コンポーネントを
+  bare 参照のまま渡すことは想定しない**（仮引数 1 個になり `DomFill` 側に誤判定される）。fillProps を
+  受け取りたい場合は bare 参照のまま渡さず `withFillProps` でラップすること（マーカー付きオブジェクトに
+  なるため、この arity 判別より前で見分けがつき衝突しない）。
+
+### React Fill の例（props なし）
+
+```tsx
+ctx.ui.fill('unit-editor.unit-toolbar', function MyToolbarButton() {
+  return <button type="button">My Button</button>;
+});
+```
+
+### React Fill の例（withFillProps で Slot の fillProps を受け取る）
+
+```tsx
+import { withFillProps } from '@ablogcms/plugins';
+import type { UnitToolbarSlotFillProps } from '@ablogcms/unit-editor/components/unit-toolbar/presets/common-toolbar';
+
+ctx.ui.fill(
+  'unit-editor.unit-toolbar',
+  withFillProps<UnitToolbarSlotFillProps>(({ editor, unit }) => (
+    <button type="button">{unit.type}</button>
+  ))
+);
+```
+
+### DOM コールバック Fill の例
+
+```ts
+ctx.ui.fill('unit-editor.unit-toolbar', (el) => {
+  const badge = document.createElement('span');
+  badge.textContent = 'Sample(DOM)';
+  el.append(badge);
+  return () => badge.remove(); // アンマウント時のクリーンアップ
+});
+```
+
+## レジストリ一覧
+
+「種類の登録」はイベント（収集パターン）ではなく列挙可能なレジストリで提供する
+（`packages/frontend/plugins/src/core/create-registry.ts`）。
+
+| レジストリ | API | 実体 | コアの組み込み定義とのマージ |
+|---|---|---|---|
+| ユニットタイプ | `ctx.unitEditor.registerUnitDefinition(name, def: UnitDefInterface)` | `createRegistry<UnitDefInterface>('unit-definition')` | `ablogcms/js/src/features/unit-editor/unit-definitions.ts` が `mergeRegistryEntries(coreUnitDefs, getUnitDefinitionRegistry())` でマージ（`{ 'rich-editor': RichEditorUnitDef, custom: CustomUnitDef, ...registry.getAll() }`。`rich-editor`/`custom` は本体固有の実装に依存するため `@ablogcms/unit-editor` のコアには置かず本体側から注入する。キー衝突時はレジストリ側が勝つ） |
+| dataview カラム型 | `ctx.dataview.registerColumnType(name, type: ColumnTypeDef)` | `createRegistry<ColumnTypeDef>('column-type')` | `features/entry/utils/index.ts` / `features/module/utils/index.ts` が `{ ...ENTRY_COLUMN_TYPES, ...getColumnTypeRegistry().getAll() }` の形でマージ |
+| dataview 行アクション | `ctx.dataview.registerAction(view, name, def: Action<RowData>)`（`view` は `'entry' \| 'module'`。将来 `'user'`/`'category'` 等へ拡張可能な文字列 union） | `createViewedRegistry<Action<RowData>>('dataview-action')`（`view` ごとに独立した名前空間を持つ。同じ `name` でも `view` が違えば衝突しない） | `use-entry-admin-actions.tsx` / `use-module-admin-actions.tsx` が `[...coreActions, ...Object.values(getDataviewActionRegistry().getAll(view))]` をコア定義 → レジストリの順で連結し、その結果をレガシー `getActions`（`ACMS.Config.entryAdminConfig.getActions` 等）へそのまま渡す（コア → レジストリ → レガシー getter の3段マージ。既存 getter 利用者は要素数が増えるだけで挙動は変わらない） |
+| dataview 一括アクション | `ctx.dataview.registerBulkAction(view, name, def: BulkAction<RowData>)` | `createViewedRegistry<BulkAction<RowData>>('dataview-bulk-action')` | `use-entry-admin-bulk-actions.tsx` / `use-module-admin-bulk-actions.tsx` が上記と同じ3段マージ（`getBulkActions` へ連結後の配列を渡す） |
+| dataview メニュー | `ctx.dataview.registerMenu(view, name, def: Menu<RowData>)` | `createViewedRegistry<Menu<RowData>>('dataview-menu')` | `use-entry-admin-menus.tsx` / `use-module-admin-menus.tsx` が上記と同じ3段マージ（`getMenus` へ連結後の配列を渡す） |
+| 翻訳（i18n） | `ctx.i18n.addResources(lng, resources)` | `index.js` が生成する `ACMS.i18nResources`（`@ablogcms/i18n/core` の受け皿） | 名前空間はプラグイン名に固定され、参照は `ACMS.i18n('my-plugin:key')` または `import { t } from '@ablogcms/i18n'` の `t('my-plugin:key')`（i18next 標準の `ns:key` 記法）。同じ言語へ何度でも追加でき既存とマージされる。`setup(ctx)` の時点では i18next 未初期化のことがあるため、登録は受け皿に溜まり初期化側がまとめて取り込む。`unregister` 時に名前空間ごと破棄される |
+| キーボードショートカット一覧 | `ctx.keyboardShortcuts.registerCategory(id, category)` / `ctx.keyboardShortcuts.registerShortcut(id, shortcut)` | 管理画面コアが所有する `@ablogcms/keyboard-shortcut` のレジストリ | `dispatch-keyboard-shortcut-modal.tsx` が開くモーダルでカテゴリー別に表示。プラグイン名で内部的に名前空間を分離するため、`shortcut.categoryId` には同じプラグイン内で登録したカテゴリーの `id` を指定する。`unregister` 時にはカテゴリー・ショートカットとも自動解除される |
+| ブロックタイプ（BLOCK_DEFINITIONS） | `ctx.blockEditor.registerBlockDefinition(name, factory: (tiptap: Tiptap) => BlockDefinition)` | `createRegistry<BlockDefinitionFactory>('block-definition')` | `ablogcms/js/src/features/block-editor/block-definitions.ts` の `getBlockDefinitions(tiptap)` がファクトリを tiptap で評価し、`@ablogcms/block-editor` の `normalizeSettings(raw, blockDefinitions)` / `resolveCommands(commands, recordUsage, blockDefinitions)` が `{ ...BLOCK_DEFINITIONS, ...blockDefinitions }` でマージ（キー衝突時はレジストリ側が勝つ） |
+| Tiptap 拡張（スキーマ層） | `ctx.blockEditor.registerExtension(name, factory: (tiptap: Tiptap) => AnyExtension \| AnyExtension[])` | `createRegistry<BlockExtensionFactory>('extension')` | 同ファイルの `getBlockExtensions(tiptap)` がファクトリを tiptap で評価しフラット化したものを、`useBlockEditor` の `extensions` prop 経由で `ExtensionKit` の後段に追加登録 |
+
+- `add(name, item)` は **`name` が既に登録済みなら throw** する（`[@ablogcms/plugins] {label} "{name}" は
+  既に登録されています。`）。警告に留めず例外にする点が WordPress（console warning のみ）と異なる、
+  a-blog cms の strict 方針。
+- `getAll()` で登録済み項目を列挙できる。名前・登録内容のデバッグは `ACMS.plugins.getAll()`
+  （どのプラグインが何を登録したか。`RegisteredPlugin.registrations`）でも追える。
+- キーボードショートカットは、管理画面コアが所有するレジストリへ本番 bootstrap（`admin.js`）で明示的に
+  注入する。外部プラグインは `@ablogcms/keyboard-shortcut` を直接 import せず、`setup(ctx)` の
+  `ctx.keyboardShortcuts` を使うことで別バンドルでもコアと同じレジストリを共有できる。
+- 実体（`Registry<T>` インスタンス）はページ全体で 1 つのシングルトンに固定される
+  （`packages/frontend/plugins/src/core/global-singletons.ts` の `getUnitDefinitionRegistry()` /
+  `getColumnTypeRegistry()` / `getBlockDefinitionRegistry()` / `getBlockExtensionRegistry()`）。
+  `createPluginRegistry()` 自体は依存注入可能な素の工場関数のままで、本番の結線（`admin.js`）だけが
+  このシングルトンを明示的に注入する。
+- **ブロックタイプ / Tiptap 拡張だけは「値そのもの」ではなく「ファクトリ」を登録する**点が他の
+  レジストリと異なる。ブロックエディターは `webpackChunkName: "block-editor"` の lazy チャンクであ
+  り、プラグイン登録時点（`<script type="module">` 読み込み時）ではまだチャンクがロードされておらず
+  Tiptap の値を要求できないため。ファクトリ（`(tiptap: Tiptap) => ...`）は、実際にブロック
+  エディターのチャンクがロードされた時点（`ablogcms/js/src/features/block-editor/block-definitions.ts`
+  の `getBlockDefinitions`/`getBlockExtensions` 経由）で呼ばれる。ファクトリが throw した場合は
+  そのエントリだけスキップし `console.error` でログする（1 プラグインの不具合でエディター全体を
+  止めない）。`Tiptap` 型・`tiptap` 値は `@ablogcms/block-editor/tiptap`
+  を参照（詳細は [PACKAGING.md](../PACKAGING.md)「Tiptap / ProseMirror の再エクスポート」節）。
+- **ファクトリは Promise を返してもよい**（解決側が `await` する）。公式 Tiptap 拡張
+  （`@tiptap/extension-*`）は `export const X = Node.create({...})` のように**モジュール評価時**に
+  Tiptap のクラスを使うため、プラグイン読み込み時点（チャンク未ロード）に評価されると成立しない。
+  ファクトリの中で `await import('@tiptap/extension-details')` と書けば、評価自体をチャンクロード後
+  （＝ランタイムが揃った後）まで遅らせられる。**登録そのものは従来どおり `setup()` 内で同期的に
+  完了する**ため、「登録 → コアの消費」の順序保証は変わらない。reject した場合の扱いは throw と同じ
+  （そのエントリだけスキップ）。
+- ファクトリを呼ぶ直前に、ホストの Tiptap ランタイムが `ACMS.Library.tiptap` へ公開される
+  （React が `ACMS.Library.React` で共有されているのと同じ置き場）。プラグイン側のバンドラ設定が
+  externals の宛先として使う（[プラグイン側のビルド設定](#プラグイン側のビルド設定react--tiptap-の共有)参照）。
+  **チャンクロード前は `undefined`** で、ファクトリの中でだけ存在が保証される。
+- カスタムブロックの作り方（`registerBlockDefinition` + `registerExtension` + 編集設定への type
+  追加の 3 点セット）は「新しい拡張ポイントを追加するときのルール」の後にサンプル付きで別掲する
+  （[カスタムブロックの作り方](#カスタムブロックの作り方)参照）。
+- **`registerExtension` で登録した Tiptap 拡張は、`addOptions()` 内で `blockMenu` プロパティを宣言する
+  ことで BlockMenu（統合ブロックツールバー）にツールバー項目を追加できる**。これは新しいレジストリ
+  ではなく、既存の Tiptap 拡張登録の延長線上にある宣言（コロケーション）で、BlockMenu が
+  `editor.extensionManager.extensions` を走査して収集・描画する。詳細・使い分けの指針・コード例は
+  「[ブロックツールバーの拡張](#ブロックツールバーの拡張)」節を参照。
+
+## 既存の購読可能イベント（DOM CustomEvent・レガシー名前空間）
+
+以下は a-blog cms が従来から使ってきた「DOM CustomEvent 経由」「レガシー `ACMS.dispatchEvent` 経由」の
+連携イベント一覧。**撤廃はしない**。テーマ側・プラグイン側の既存購読を壊さないため、発火自体は今後も
+継続する。
+
+### ミラー方針（レガシーとの併走）
+
+Phase 3（`docs/steering/20260731-js-extension-points/plan.html`「レガシーイベントとの併走方針」）で、
+以下の表に載っている DOM CustomEvent・レガシー `ACMS.dispatchEvent` イベントに対応する新バス
+（`ACMS.events`）イベントを追加し、発火箇所には**新バス → レガシーの順**で両方を並記した
+（`void ACMS.events.notify('新イベント名', payload); triggerEvent(...)` / `ACMS.dispatchEvent(...)`）。
+「新バスの同等イベント」列がそれに対応する。
+
+同じ方針で `admin.js` 内部の中継系レガシーイベント（`acmsAdminDelayedContents` / `acmsDialogOpened` /
+`acmsAdminSelectTab` / `acmsAdminShowTabPanel` / `acmsAdminHideTabPanel` / `onGeoInfoAdded` /
+`acmsInplaceDialogOpen` / `acmsAddCustomFieldGroup` の8種）も並記済みだが、これらは独立した連携イベント
+表を持たず、対応する新バスイベント（`admin.delayed-contents.change` / `dialog.open.after` /
+`tab.select.change` / `tab.show.after` / `tab.hide.after` / `geo.info-add.after` /
+`unit-editor.inplace-dialog-open.after` / `field-group.add.after`）側の「イベント一覧」表
+（上記）の発火箇所列にレガシー対応を記載している。
+
+- **なぜ両方発火するか**: 新バスへ完全移行すると、既存テーマ・既存プラグインの購読（`document.addEventListener`
+  や `ACMS.addListener`）が届かなくなり後方互換が壊れる。かといって新バス側を追加しないと、新規プラグインが
+  `.before` ゲート（キャンセル・値変更・非同期待機）の恩恵を受けられない。両方式には契約の違い
+  （新バスは型安全・ゲート対応・再生なし、レガシーはノーガード・型なし・`ACMS.dispatchEvent` 経由のもの
+  だけ `eventPool` 再生あり）があるため、統合ではなく「並記」を選んだ。
+- **どちらを購読すべきか**: 新規のプラグイン・拡張は新バス（`ACMS.events.on(...)`）を使う。既存のテーマ
+  カスタマイズ（DOM CustomEvent 購読）はそのままで良く、移行を強制しない。
+- **例外（ミラーしない）**: 起動系イベント（次節）は契約上ミラーできないため対象外。
+- **`acmsCustomFieldMakerPreview` の扱い**: 発火元は npm 依存 `custom-field-maker`（v1.6.8）側で本体では
+  制御できないため、レガシー発火そのものは維持する。ただし購読側は `custom-field-maker.preview.after`
+  （中継ブロック 1 箇所、`admin.js`）へ移行済み（上記「イベント一覧」参照）。
+
+新規拡張ポイントは今後も新バス（`ACMS.events`）側にのみ追加する。以下は「既に存在する連携イベント」と
+してそのまま利用できる（新バス側のイベントは上表「イベント一覧」を参照）。
+
+| イベント名 | 発火方法 | 発火箇所 | 新バスの同等イベント | 用途 |
+|---|---|---|---|---|
+| `acms.media-updated` | `triggerEvent`（= `el.dispatchEvent(new CustomEvent(...))`。標準 DOM API） | `packages/frontend/media/src/components/media-modal/media-modal.tsx`（メディア編集の保存後） | `media.update.success` | メディア更新の通知。`block-editor` の Image/FileBlock、`media-unit`、`dispatch-media-field` 等、8 箇所以上で `document.addEventListener` / React `useEffect` cleanup で購読・解除している |
+| `acms.set-main-image` | 標準 `CustomEvent` | `packages/frontend/block-editor/src/extensions/ImageBlock/components/ImageBlockMenuSection.tsx` | `entry.main-image.change` | メイン画像設定の連携 |
+| `acms.category.change` | `triggerEvent` | `ablogcms/js/src/features/category/mount-category-select.tsx` | `category.select.change` | カテゴリー選択変更の連携（`mount-sub-category-select.tsx` 等が購読） |
+| `acms.sub-category.change` | `triggerEvent` | `ablogcms/js/src/features/sub-category/mount-sub-category-select.tsx` | `sub-category.select.change` | サブカテゴリー選択変更の連携 |
+| `acms.tag.change` | `triggerEvent` | `ablogcms/js/src/features/tag/mount-tag-select.tsx` | `tag.select.change` | タグ選択変更の連携 |
+| `acms.related-entry.change` | `triggerEvent` | `ablogcms/js/src/features/related-entry/mount-related-entry.tsx` | `related-entry.select.change` | 関連エントリー変更の連携 |
+| `acms.media-field.change` | `triggerEvent` | `ablogcms/js/src/dispatch/media/dispatch-media-field.tsx` | `media-field.change` | メディアフィールド変更の連携 |
+| `acms.media-unit.change` | `triggerEvent` | `packages/frontend/media/src/setup-media-unit.tsx` | `media-unit.change` | メディアユニット変更の連携（`detail: { mediaItems }` 付き） |
+| `acmsUnitEditorCreate` | **レガシー `ACMS.dispatchEvent`**（`eventPool` 経由。後述の非推奨 API） | `packages/frontend/unit-editor/src/components/unit-editor/index.tsx` | `unit-editor.create.after` | ユニットエディタ生成時の通知。`ACMS.addListener` で購読すると発火済みなら再生される |
+| `acmsAddUnit` | **レガシー `ACMS.dispatchEvent`** | `unit-editor/index.tsx` / `inplace-editor.tsx`（v3.2 未満互換） | なし | サーバサイドユニット描画時の通知 |
+| `acmsCustomFieldMakerPreview` | **npm 依存 `custom-field-maker`（v1.6.8）の `window.ACMS.dispatchEvent`** | `node_modules/custom-field-maker/lib/components/{Field,Unit,FieldGroup,UnitGroup}Source.js` | `custom-field-maker.preview.after` | プレビュー再描画の通知（`payload: { item: HTMLElement }`）。発火元はリポジトリ内ではなく npm 依存パッケージ側のため、発火自体はレガシーのまま維持。`admin.js` の中継ブロック（1 箇所）が新バス `custom-field-maker.preview.after` へ変換し、購読側 4 箇所はそちらに移行済み |
+
+- 上 8 件（`acms.media-updated` 〜 `acms.media-unit.change`）は標準 DOM API（`triggerEvent`。
+  `@ablogcms/utils` の薄いラッパーで `CustomEvent` + `dispatchEvent` を呼ぶ。`acms.set-main-image` のみ
+  `triggerEvent` を介さず素の `new CustomEvent` + `dispatchEvent` を直接呼ぶ）で発火され、標準の
+  `document.addEventListener` / `removeEventListener` で購読する。**再生（eventPool）は行われない**ため、
+  購読側は発火より前に登録されている必要がある。
+- 続く 3 件（`acmsUnitEditorCreate` / `acmsAddUnit` ）は実装上レガシーな `ACMS.dispatchEvent` を経由しており、
+  `ACMS.addListener` で購読すると `eventPool` の再生対象になる（後から購読しても過去の発火分が届く）。
+  同じ「DOM CustomEvent」でも発火経路によってこの挙動差があることに注意。
+- 最後の `acmsCustomFieldMakerPreview` は発火元が本体のソースコード内に存在しない唯一の例。同じく
+  レガシー `ACMS.dispatchEvent` 経由（`eventPool` の再生対象）。購読側は `admin.js` の中継ブロック
+  （1 箇所）が新バス `custom-field-maker.preview.after` へ変換する形にすでに移行済み（上記「イベント一覧」参照）。
+- これらの名前・発火は**非推奨にしない**。現役の連携イベントとして維持する。
+
+### 起動系イベント（`.ready` フェーズと `ACMS.readyStates`）
+
+「特定の初期化が完了した」ことを示す一度きりの起動系イベントは、`ACMS.addListener` の
+`eventPool` 再生（発火後に購読しても過去の発火分がその場で再生される）に依存する契約になっている。
+初期化完了のタイミングは購読側コードの読み込みタイミングより後になるとは限らないため、
+「後から購読しても取りこぼさない」という保証が本質的に必要な唯一の用途であり、`ACMS.events`
+（新バス）は意図的に再生機構を持たない設計（`warnLateSubscription`。上記「レガシー API の
+非推奨一覧」の `ACMS.eventPool` 行参照）のため、単純に `notify`/`on` へ置き換えると「発火後に
+`ACMS.events.on(...)` した購読者には届かない」という契約破りになる。
+
+この契約を保ったまま新バスへ移行するため、`ACMS.readyStates`（`document.readyState` と同じ
+発想のプレーンなオブジェクト。各キーが `'loading'` → `'complete'` と遷移する）を導入した。
+購読側は「対応するキー（`ACMS.readyStates.ready` 等）が `'complete'` なら即時実行、そうでなければ
+`ACMS.events.on(...)` で購読する」を自前で分岐すればよく、`ACMS.Ready`（`ablogcms/acms.js`）自身が
+その参照実装。バス全体に汎用の再生機構を持たせてしまうと、繰り返し発火する通常の通知イベント
+（`dialog.open.after` 等）まで誤って再生対象になってしまうため、意図的にイベント単位
+（`readyStates` のキーを個別に用意する形）のオプトインにしている。
+
+| イベント名（新バス） | フェーズ | 対応するレガシーイベント | 発火箇所 |
+|---|---|---|---|
+| `acms.state.ready` | `.ready`（`ACMS.readyStates.ready === 'complete'` かどうかを先に見てから購読すること。直接 `on()` しない） | `acmsReady`（`ACMS.Ready(listener)`） | `ablogcms/js/src/index.js`。`ACMS.readyStates.ready = 'complete'` を設定した直後に発火する |
+| `acms.state.admin-ready` | `.ready`（`ACMS.readyStates.adminReady === 'complete'` かどうかを先に見てから購読すること） | `acmsAdminReady` | `ablogcms/js/src/admin.js`。`ACMS.readyStates.adminReady = 'complete'` を設定した直後に発火する |
+| `acms.pending.ready` | `.ready`（`ACMS.pendingReadyState === 'complete'` かどうかを先に見てから購読すること） | なし（**ミラーしない**。下記参照） | `ablogcms/js/src/dispatch/dispatch-pending.tsx`。`ACMS.pendingReadyState = 'complete'` を設定した直後に発火する |
+
+`acmsReady`/`ACMS.Ready` を移行できた決め手は発火場所の見直し: `ACMS.events` は元々 `admin.js`
+（ログイン中の投稿権限者にしか読み込まれない）でのみ生成していたが、`acmsReady` を発火する
+`index.js` は非ログイン閲覧者を含むあらゆるセッションで読み込まれるため、`admin.js` を前提に
+すると `ACMS.events` 自体が存在しない状況が構造的に残ってしまう。そこで **バスの生成自体を
+`index.js` 側へ移した**（`admin.js` 側は既存インスタンスがあればそれを使い、無ければ自分でも
+生成する防御的な実装のまま）。`ACMS.Ready` 自体は `acms.js`（同期・ブロッキングで最初に実行
+される、非バンドルのプレーンスクリプト）に定義したまま変えていない。`ACMS.readyStates.ready`/
+`ACMS.events` というプレーンなグローバルを参照するだけなので、`import` を必要とする
+`@ablogcms/events` を持ち込まずに済む。ただし `ACMS.events` が万一まだ存在しない（`index.js`
+より前に実行されるインラインスクリプト等からの呼び出し）場合に備え、レガシー
+`ACMS.addListener('acmsReady', listener)` へのフォールバックも残している。
+`ACMS.dispatchEvent('acmsReady')` 自体も後方互換のため残し、新バスとの二重発火にしている
+（「レガシーとの併走方針」）。`acms.state.admin-ready` も同様に `ACMS.dispatchEvent('acmsAdminReady')`
+と二重発火する。
+
+`acms.pending.ready` は例外で、対応するレガシー `acmsPendingReady`（`ACMS.dispatchEvent` 経由）を
+**ミラーせず置き換えている**（`ablogcms/js/src/dispatch/dispatch-pending.tsx`）。社内に
+`acmsPendingReady` の購読側コードが無く、後方互換のためだけに二重発火し続ける動機が薄いため、
+他の起動系イベント（`acms.state.ready` / `acms.state.admin-ready`）とは異なり移行時点で
+レガシー発火自体を廃止した。既存テーマ・プラグインが `acmsPendingReady` を購読していた場合は
+このバージョンで届かなくなる点に注意（`ACMS.Library.pending` の available 時に必要なら
+`acms.pending.ready` へ購読を切り替えること）。
+
+以下は同種の「起動系」だが、社内に移行する購読側コードが現時点で無いため、今回は据え置いている。
+将来、社内購読を新設する場合は `acms.state.ready`/`ACMS.readyStates` と同じパターン
+（イベントごとに `Xxx.readyState`（または `readyStates` オブジェクトのプロパティ）を 1 つ用意し、
+`.before` を経由せず先にチェックしてから購読する）で個別に移行を検討すること。
+
+| イベント名 | 発火箇所 | 据え置き理由 |
+|---|---|---|
+| `${スクリプトファイル名}Ready`（動的名） | `packages/frontend/lib/src/loader/loader.js:77`。読み込んだ URL のファイル名から動的に組み立てる | 名前が実行時にしか決まらない動的イベントのため、そもそも `AcmsEventMap` のような静的なイベント名の型定義に載せられない |
+
+`configLoad`（`ablogcms/js/src/index.js`、公開側の設定読み込み完了）はレガシー `ACMS.dispatchEvent`
+呼び出し自体を削除済み（新バスへの移行・据え置きのどちらでもなく廃止）。社内に購読側コードが無く、
+既存テーマ・プラグインからの購読実績も確認されていないための削除だが、外部の未把握の購読者が
+存在した場合は届かなくなる点に注意すること。
+
+## レガシー API の非推奨一覧と移行例
+
+**撤廃はしない。挙動・シグネチャも変えない。** `ACMS.dispatchEvent` / `ACMS.addListener` / `ACMS.eventPool` は
+型定義（JSDoc）に `@deprecated` と移行先を明示した（`packages/frontend/types/src/acms.d.ts`、
+`ablogcms/js/src/types/acms.d.ts`）。`entryAdminConfig` / `moduleAdminConfig` の getter 群は、利用者が編集する
+`ablogcms/js/config.js` の素の関数で型定義を持たず `@deprecated` も付けていないため、この表の記述でのみ
+非推奨として扱う。
+
+| 対象 | 宣言箇所 | 移行先 | 備考 |
+|---|---|---|---|
+| `ACMS.dispatchEvent` | `ablogcms/acms.js`（実装）/ `packages/frontend/types/src/acms.d.ts`（型。registry 側の骨格メンバー） | `ACMS.events.notify` / `ACMS.events.gate`（`@ablogcms/events`） | 発火の意味論が全く異なる（後述） |
+| `ACMS.addListener` | 同上 | `ACMS.events.on` | 同上 |
+| `ACMS.eventPool` | `ablogcms/acms.js`（実装）/ `ablogcms/js/src/types/acms.d.ts`（型。アプリ内部専用メンバーとして追記） | （代替 API なし。`ACMS.events` は意図的に再生を持たない） | 直接参照している外部コードがあれば、まず無くすことを検討する |
+| `ACMS.Config.entryAdminConfig` の `getActions`/`getBulkActions`/`getMenus` | `ablogcms/js/config.js`（typedef なしの素の関数。`@deprecated` は付けていない） | `ctx.dataview.registerAction`/`registerBulkAction`/`registerMenu`（`view: 'entry'`） | レジストリ登録分はコア定義の後ろに追加された上でこの getter にも渡る（3段マージ）ため、getter は引き続き使えるが新規実装はレジストリを推奨する |
+| `ACMS.Config.entryAdminConfig` の `getColumns`/`getValues` | 同上 | （代替レジストリなし。`getColumns` は列の並び替え/削除、`ctx.dataview.registerColumnType` はカラム**型**の追加であり別の関心事） | 一覧系のこの2つはレジストリ整備が未着手のため、**「非推奨だが唯一の手段」** の注記付き |
+| `ACMS.Config.moduleAdminConfig` の同上 getter 群 | `ablogcms/js/config.js`（typedef なしの素の関数。`@deprecated` は付けていない） | 同上（`view: 'module'`） | 同上 |
+
+### getColumns で追加した列の表示位置と表示状態
+
+`getColumns` の戻り値に新しい列を足すと、その**配列上の位置がそのまま既定の表示位置**になる。
+列の表示順は「サーバーに永続化されたユーザーの表示項目設定 ＋ 本体の既定順（`ENTRY_COLUMN_ORDER` /
+`MODULE_COLUMN_ORDER`）」で決まり、そこに載っていない id は
+`resolveColumnOrder`（`@ablogcms/components/dataview/utils`）が「配列上で直前にある既知の列の直後」へ
+差し込む。`code` の隣に置きたければ `code` の直後に `splice` する。
+
+```ts
+ACMS.Config.entryAdminConfig.getColumns = (columns) => {
+  const index = columns.findIndex((column) => column.id === 'code');
+  return [
+    ...columns.slice(0, index + 1),
+    { id: 'stock', label: '在庫', type: 'display', getValue: (info) => renderStockBadge(info.row.original) },
+    ...columns.slice(index + 1),
+  ];
+};
+```
+
+- 追加した列は**初期状態で表示**扱いになる（表示項目設定に保存された値が無い列は「表示」と解釈する）。
+  管理画面の「表示項目設定」ドロワーにもチェック済みで並び、ユーザーがドラッグで並び替えて保存すれば
+  その順序・表示状態が永続化され、以降は保存値が上記の既定位置より優先される。
+- 表示項目設定に出したくない列は `enableHiding: false` を指定する（ドロワーの一覧から除外され、
+  ユーザーは非表示にできなくなる）。
+
+### 移行例
+
+```ts
+// Before（レガシー）
+ACMS.addListener('acmsSomeEvent', (event) => {
+  console.log(event.detail);
+});
+ACMS.dispatchEvent('acmsSomeEvent', document, { foo: 1 });
+
+// After（新設ハブ）
+declare module '@ablogcms/events' {
+  interface AcmsEventMap {
+    'some.thing.success': AcmsNotifyEvent<{ foo: number }>;
+  }
+}
+ACMS.events.on('some.thing.success', (payload) => {
+  console.log(payload.foo);
+});
+await ACMS.events.notify('some.thing.success', { foo: 1 });
+```
+
+`ACMS.dispatchEvent`/`addListener` は「発火済みイベントの再生（`eventPool`）」「DOM への実バブリング」を
+前提にした設計であり、`ACMS.events` の「登録順 waterfall・キャンセル・非同期ゲート」とは意味論が違う。
+既存コードの機械的な置換はできないため、移行は新規拡張ポイントから始め、レガシー領域
+（`admin.js` の `acmsAdminDelayedContents` 等）は当面そのまま残す。
+
+ランタイム deprecation 警告（WordPress `@wordpress/deprecated` 方式: 一度だけ console 警告）は追加しないことで
+確定した（`docs/steering/20260731-js-extension-points/plan.html` 確定事項 Q8）。`ACMS.dispatchEvent` は
+レガシーとの併走（二重発火）方針により a-blog cms 自身のコードから今後も恒久的に呼び出し続ける設計のため、
+警告を付けると鳴りっぱなしになる。`ACMS.addListener` は内部購読をほぼ新バスへ移行済みだが、残る自社コードの
+呼び出し（次節の ESLint ルールで許可リスト化している箇所）を「警告の出ない内部専用エイリアス」へ書き換える
+追加実装が必要になり、コストに見合わないと判断した。型定義（JSDoc）の `@deprecated` 注記のみで運用する。
+
+### ESLint による新規使用の抑止（`ACMS.addListener` のみ）
+
+`eslint.config.mjs` の `no-restricted-syntax` に `ACMS.addListener` 呼び出しを検出するセレクタを追加し、
+自社コード（`ablogcms/js/src/**` / `packages/frontend/**/src/**`。ESLint 対象外の `ablogcms/js/dispatch/**`
+等は元々対象外）内での**新規**呼び出しを禁止している。`ACMS.dispatchEvent` は上記の理由（恒久的に
+呼ばれ続ける設計）により対象にしていない。
+
+- 既存の維持対象呼び出し（`admin.js` の新バスへの中継ブロック 5 箇所。`acmsAdminDelayedContents` 系
+  4 箇所と `acmsCustomFieldMakerPreview` を `custom-field-maker.preview.after` へ変換する 1 箇所）は、
+  誤検知ではなく個別に `// eslint-disable-next-line no-restricted-syntax -- <理由>`
+  を付けて明示的に許可している。新しくこのパターンを増やす場合も同様にコメントで理由を残すこと。
+  `built-in/dispatch.js` の wysiwyg/flatpicker 初期化 2 箇所（旧: `acmsAddCustomFieldGroup` 購読）は
+  `on('field-group.add.after', ...)` へ移行済み（この関数は `index.js` から呼ばれる際に
+  必ず `ACMS.events` 生成後に実行されるため、`ACMS.events が無い場合がある` という当初の懸念は
+  当てはまらないと判明した）。`packages/frontend/lib/src/open-street-map/picker/index.ts` も
+  新バス移行後の呼び出し。
+- 新規コードで `ACMS.addListener` が必要になった場合は、まず `ACMS.events.on`（新バス）で要件を満たせないか
+  検討する。既存の DOM CustomEvent（前節の「既存の購読可能イベント」）を購読したいだけなら、対応する
+  「新バスの同等イベント」があればそちらを使う。
+
+## `ctx.config` の制約
+
+`jsModule($key, $value)`（PHP）→ `ACMS.Config.{camelCase(プラグイン名)}` → `ctx.config`
+（`packages/frontend/plugins/src/core/create-plugin-registry.ts` の `readConfig`）という経路で、PHP 側の
+設定値をプラグインの `setup(ctx)` から参照できる。実体は `ACMS/GET/Js.php` が
+`http_build_query(Common::getJsModules())` で組み立てたクエリ文字列を `acms.js?...` に付与し、
+`index.js` が `qs.parse()` で読み戻して `ACMS.Config` に展開する URL エンコード方式であり、次の制約がある
+（実測で確認）:
+
+- **スカラー値はすべて文字列化される**。PHP の `42`（int）は JS 側で `"42"`（string）になる。
+  `true`/`false` も `http_build_query` によって `"1"`/`"0"` という文字列に変換される
+  （`bool` として届かない）。
+- **`null` はキーごと消失する**。`http_build_query` は値が `null` のキーを出力しないため、
+  `ctx.config` にそのキー自体が現れない（`undefined` と区別できない）。
+- **ネストは `qs` の既定 depth（5）までしか保たれない**。6 段目以降のキーは最後の階層が
+  `"[key]"` という文字列そのもののプロパティ名として扱われ、意図した入れ子にならない
+  （実測: `deep[l1][l2][l3][l4][l5][l6]=x` → `deep.l1.l2.l3.l4.l5['[l6]']` になり `l6` は消えない代わりに
+  ネストが崩れる）。**深い設定はネストではなくフラットなキーで渡す**か、JSON 文字列 1 本を値として渡し
+  プラグイン側で `JSON.parse` する。
+- **秘匿情報（API キー・トークン等）を `ctx.config` に流さない**。クエリ文字列はブラウザの開発者ツール・
+  アクセスログ等から容易に閲覧できる。秘匿が要る連携はサーバ側 PHP（Hook / 独自エンドポイント）で行う
+  こと（kintone が `setConfig`（クライアント露出）と `setProxyConfig`（サーバ側秘匿）を分けているのと
+  同じ考え方）。専用のプロキシ API は将来課題。
+- `ctx.config` はプラグイン名をキャメルケース変換して `ACMS.Config` を引く（`-`/`_` 区切りの次の文字を
+  大文字化）。未初期化・未設定時は例外を投げず空オブジェクト `{}` を返す。
+
+## `ctx.ui.fill` で fillProps を受け取る（withFillProps）
+
+- `ctx.ui.fill(slotName, entry)` に素の関数コンポーネント（`() => ReactNode`）や `DomFill`
+  （`(el) => ...`）をそのまま渡した場合、`Slot` 側の `fillProps` は転送されない
+  （`resolveFillEntry` が 0 引数の関数を「props なしの React コンポーネント」として
+  `createElement(entry)`（引数なし）で描画するため）。これは既存の後方互換として維持しており、
+  0 引数の Fill コンポーネントの挙動は変わらない。
+- `Slot` の `fillProps`（`unit-editor.unit-toolbar` の `editor`/`unit` 等）を `ctx.ui.fill` 経由で
+  受け取りたい場合は、コンポーネントを `withFillProps`（`@ablogcms/plugins`）でラップして渡す。
+  ```tsx
+  import { withFillProps } from '@ablogcms/plugins';
+
+  ctx.ui.fill(
+    'unit-editor.unit-toolbar',
+    withFillProps<UnitToolbarSlotFillProps>(({ editor, unit }) => <button type="button">{unit.type}</button>)
+  );
+  ```
+- **npm パッケージを import できない外部プラグイン**（`InjectTemplate::add()` で読み込まれる
+  `<script type="module">`）は、`ACMS.plugins.withFillProps` としてグローバルからも同じ関数を呼べる
+  （`AcmsPlugins` インターフェースのメンバー。実体は `@ablogcms/plugins` の `withFillProps` と同一）。
+  ```js
+  ACMS.plugins.register('my-plugin', {
+    setup(ctx) {
+      const { withFillProps } = ACMS.plugins;
+      ctx.ui.fill('unit-editor.unit-toolbar', withFillProps(({ editor, unit }) => (
+        window.React.createElement('button', { type: 'button' }, unit.type)
+      )));
+    },
+  });
+  ```
+- `withFillProps` は関数ではなく `{ kind: 'acms-plugins/fill-component', Component }` という
+  マーカー付きオブジェクトを返す（`packages/frontend/plugins/src/core/with-fill-props.ts`）。
+  Why not（関数のままオーバーロードを増やさない理由）: props を要求するコンポーネント
+  （`({ editor, unit }) => ...`）は仮引数が 1 個になり、`DomFill`（`(el) => ...`）と実行時に
+  `Function.prototype.length` だけでは区別できない。オブジェクトでラップすることで、既存の
+  「0 引数 = props なしコンポーネント／1 引数以上 = DomFill」という arity 判別ロジックを一切
+  変更せずにこの衝突を避けている。
+- `resolveFillEntry` は `withFillProps` のエントリを受け取ると、`fillProps` を受け取る render-prop
+  形式の関数（`FillRenderer<T>`）を返す。`Slot`（`@ablogcms/components/slot-fill`）はもともと
+  「render が関数なら fillProps を渡して呼ぶ」実装を持っていたため、`ctx.ui.fill` 側の変更だけで
+  Slot 側には手を入れていない。
+- `withFillProps` に渡せるのは関数コンポーネントのみ（クラスコンポーネントは非対応）。本リポジトリは
+  新規のクラスコンポーネント追加を禁止する規約（development-guidelines.md）のため制約にはならない。
+
+## プラグイン側のビルド設定（React / Tiptap の共有）
+
+プラグイン JS は `InjectTemplate::add()` から `<script type="module">` として読み込まれ、npm パッケージを
+import できない。JSX や TypeScript を使うためにプラグイン側でバンドラを用意する場合、**React・Tiptap・
+ProseMirror をプラグインに同梱してはいけない**。同梱するとインスタンスが二重化し、React は hooks が
+「Invalid hook call」で壊れ、ProseMirror は `instanceof`（`NodeSelection` 判定など）や schema 互換が壊れる。
+
+| 依存 | 入手経路 | 同梱した場合 |
+|---|---|---|
+| React | グローバル `window.ACMS.Library.React`（`ablogcms/js/src/admin.js` で公開） | hooks を使った時点で壊れる |
+| react-dom | グローバル `window.ACMS.Library.ReactDom`（`react-dom`）と `window.ACMS.Library.ReactDomClient`（`react-dom/client`） | 描画エンジンが二重になる。`@floating-ui/react` が使う `createPortal` / `flushSync` も同梱版を参照してしまう |
+| `@ablogcms/components` | グローバル `window.ACMS.Library.components.<サブパス名>`（下記の一覧） | 部品のコードが二重になり、コアが更新されても見た目・挙動がプラグインのビルド時点のまま残る。`@floating-ui/react` なども同梱される |
+| React の JSX ランタイム | グローバル `window.ACMS.Library.ReactJsxRuntime`（同上） | `react/jsx-runtime` だけが同梱される。React 本体とメジャーが食い違うと要素が別形式になり描画できない |
+| Tiptap / ProseMirror | ファクトリ引数（`{ core, react, suggestion, pm }`）、または externals の宛先としてグローバル `window.ACMS.Library.tiptap`（**中身が入るのはチャンクロード後**。詳細は下記） | PM インスタンスの二重化で `instanceof` 判定・schema 互換が壊れる |
+| 型（`BlockDefinition` 等） | npm の `@ablogcms/block-editor/types` 等を `import type` で（コンパイル時に消える） | — |
+
+### 公開している `@ablogcms/components`
+
+`ACMS.Library.components` のキーは `@ablogcms/components` のサブパス名と一致する。externals の宛先は
+`var ACMS.Library.components.<サブパス名>`（ハイフンを含む名前は `components['button-v2']` の形）。
+`@ablogcms/components` の公開サブパスは**次の 8 つを除いてすべて**公開している（実体は
+`ablogcms/js/src/features/plugin-library/plugin-library.ts` の `PLUGIN_COMPONENTS`）。
+
+- 公開しないサブパス: `dataview` / `date-picker` / `time-picker` / `syntax-highlight` / `rich-select` / `select` /
+  `device-mode` / `icon-picker`。flatpickr・highlight.js・react-select などの重い依存を持ち、公開側ページにも
+  読み込まれる共通バンドルを太らせるため。これらが必要な場合は要望を出すこと。
+
+```js
+// webpack
+externals: {
+  react: 'var ACMS.Library.React',
+  'react/jsx-runtime': 'var ACMS.Library.ReactJsxRuntime',
+  'react-dom': 'var ACMS.Library.ReactDom',
+  'react-dom/client': 'var ACMS.Library.ReactDomClient',
+  '@ablogcms/components/popover': 'var ACMS.Library.components.popover',
+  '@ablogcms/components/button-v2': "var ACMS.Library.components['button-v2']",
+}
+```
+
+- 状態（Context・レジストリ）を持つ部品もホストの 1 つだけが使われるため、コピー間で状態が分かれない。
+- `react-dom` は全体を公開している。ホストの React と同一インスタンスなので、`createRoot` で別ルートを作っても
+  描画エンジンは二重にならない。
+
+### `ACMS.Library` と読み込み順の注意
+
+`admin.js` は `async` で読み込まれるため、`<script type="module">` のプラグインが先に実行されることがある
+（`async` は `defer` より優先され、実行順が保証されない）。その場合 `ACMS.plugins` や `ACMS.Library.React` は
+まだ無い。トップレベルでこれらを参照する前に `ACMS.adminReady(() => { ... })` で包むこと。`adminReady` は
+`admin.js` の初期化完了後に呼ばれ、すでに完了していれば即時に呼ばれる。ただしコールバック内の登録は
+「トップレベル同期登録」の前提から外れるため、core が先に参照するレジストリ（`registerUnitDefinition` 等）の
+取りこぼしがないかを確認する。
+
+### 出力形式は IIFE にする
+
+ESM 出力＋`external` にすると、バンドルに `import React from "react"` という bare specifier が残り、
+import map の無いブラウザでは解決できない（実測）。**IIFE で出力**し、`<script type="module">` から
+読み込むこと（module スコープと defer 実行はそのまま得られる）。ソースは通常どおり ESM で書いてよく、
+変えるのは出力形式だけ。
+
+コード分割（`await import()`）も両バンドラで機能する（実測）。webpack は IIFE 出力でも別チャンクを
+生成し、Vite（Rollup）は 1 ファイルに畳みつつ**評価だけを遅延**する（`__esmMin` でラップされる）ため、
+「公式 Tiptap 拡張の評価をチャンクロード後まで遅らせる」用途はどちらでも成立する。
+
+### JSX は automatic runtime のままでよい
+
+`react/jsx-runtime` も `ACMS.Library.ReactJsxRuntime` として共有しているため、
+**`@vitejs/plugin-react` や `@babel/preset-react` の既定（automatic runtime）をそのまま使える**。
+externals に 1 行足すだけでよい。
+
+```js
+// webpack
+externals: {
+  react: 'var ACMS.Library.React',
+  'react/jsx-runtime': 'var ACMS.Library.ReactJsxRuntime',
+}
+```
+
+外し忘れると `react/jsx-runtime` だけがプラグイン側に同梱される（実測）。React 本体とメジャーが
+食い違うと要素が別形式になり描画できなくなるため、必ず external にすること。
+なお開発ビルド（`react/jsx-dev-runtime`）は共有していないので、**配布物は production ビルド**で作る。
+
+### webpack
+
+```js
+// webpack.config.js
+const path = require('path');
+
+module.exports = {
+  mode: 'production',
+  entry: './src/plugin.tsx',
+  output: { path: path.resolve(__dirname, 'dist'), filename: 'plugin.js' }, // 既定で IIFE
+  externals: {
+    react: 'var ACMS.Library.React',
+    'react/jsx-runtime': 'var ACMS.Library.ReactJsxRuntime',
+    '@tiptap/core': 'var ACMS.Library.tiptap.core',
+    '@tiptap/react': 'var ACMS.Library.tiptap.react',
+    '@tiptap/suggestion': 'var ACMS.Library.tiptap.suggestion',
+    '@tiptap/pm/state': 'var ACMS.Library.tiptap.pm.state',
+    '@tiptap/pm/model': 'var ACMS.Library.tiptap.pm.model',
+    '@tiptap/pm/view': 'var ACMS.Library.tiptap.pm.view',
+    // 必要な pm サブパスを同様に（transform / commands / keymap / inputrules / tables …）
+    // externalsType: 'module' にはしないこと（bare import が残る）
+  },
+  module: {
+    rules: [{ test: /\.tsx?$/, use: 'babel-loader' }], // preset-react は既定の automatic でよい
+  },
+};
+```
+
+### Vite
+
+```js
+// vite.config.js
+import { defineConfig } from 'vite';
+import react from '@vitejs/plugin-react';
+
+export default defineConfig({
+  plugins: [react()], // automatic runtime のままでよい
+  build: {
+    lib: { entry: 'src/plugin.tsx', name: 'MyPlugin', formats: ['iife'], fileName: () => 'plugin.js' },
+    rollupOptions: {
+      external: ['react', 'react/jsx-runtime', '@tiptap/core', '@tiptap/pm/state'],
+      output: {
+        // globals は iife/umd でのみ効く
+        globals: {
+          react: 'ACMS.Library.React',
+          'react/jsx-runtime': 'ACMS.Library.ReactJsxRuntime',
+          '@tiptap/core': 'ACMS.Library.tiptap.core',
+          '@tiptap/pm/state': 'ACMS.Library.tiptap.pm.state',
+        },
+      },
+    },
+  },
+});
+```
+
+どちらの設定でも、出力は `ACMS.Library.*` を参照するだけになりホストと同一インスタンスを共有する
+（実測で確認）。ソース側は通常どおり `import React from 'react'` / `import { Node } from '@tiptap/core'`
+と書いてよい（いずれも devDependency）。
+
+> **なぜ Tiptap も externals で足りるのか**: `ACMS.Library.tiptap` は admin.js の時点で
+> 「遅延解決する名前空間」として置かれており、プロパティに触れた瞬間に実体へ委譲する。
+> Rollup の IIFE 出力が externals を読み込み時に 1 度だけ束縛する（`})(ACMS.Library.tiptap.core)`）
+> 実装でも、掴んでいるのが遅延名前空間なので後から正しい実体に届く。
+> ただし**実体が入るのはブロックエディターのチャンクがロードされた後**なので、
+> チャンクロード前に中身へ触ると「まだ使えません」という例外になる（下記参照）。
+
+
+### 公式 Tiptap 拡張（`@tiptap/extension-*`）をそのまま使う
+
+公式拡張は内部で `@tiptap/core` / `@tiptap/pm/*` を import しており、素直にバンドルすると Tiptap 一式が
+プラグイン側に取り込まれる（実測: **839KB**・生成された拡張はホストの `Mark` の `instanceof` に**ならない**）。
+`@tiptap/*` を externals にしてホストのランタイム（`ACMS.Library.tiptap`）へ向け、**ファクトリの中で
+`await import()` する**ことで共有できる（実測: 公式拡張は 1.6KB の遅延チャンクに切り出され、
+`@tiptap/core` 本体を含まない）。
+
+```js
+ACMS.plugins.register('my-plugin', {
+  setup(ctx) {
+    // 登録は setup 内で同期的に。評価だけがチャンクロード後まで遅れる
+    ctx.blockEditor.registerExtension('details', async () => {
+      const { Details } = await import('@tiptap/extension-details');
+      return Details;
+    });
+  },
+});
+```
+
+externals は機械的に列挙するだけでよい（`ACMS.Library.tiptap` は `tiptap` 値と同じ形で
+`core` / `react` / `suggestion` / `pm.*` を持つ）。
+
+```js
+// webpack
+externals: {
+  react: 'var ACMS.Library.React',
+  '@tiptap/core': 'var ACMS.Library.tiptap.core',
+  '@tiptap/react': 'var ACMS.Library.tiptap.react',
+  '@tiptap/suggestion': 'var ACMS.Library.tiptap.suggestion',
+  '@tiptap/pm/state': 'var ACMS.Library.tiptap.pm.state',
+  '@tiptap/pm/model': 'var ACMS.Library.tiptap.pm.model',
+  '@tiptap/pm/view': 'var ACMS.Library.tiptap.pm.view',
+  // 必要な pm サブパスを同様に（transform / commands / keymap / inputrules / tables …）
+}
+```
+
+```js
+// Vite（rollupOptions.output.globals も同じ宛先で並べる）
+rollupOptions: {
+  external: ['react', '@tiptap/core', '@tiptap/pm/state'],
+  output: {
+    globals: {
+      react: 'ACMS.Library.React',
+      '@tiptap/core': 'ACMS.Library.tiptap.core',
+      '@tiptap/pm/state': 'ACMS.Library.tiptap.pm.state',
+    },
+  },
+},
+```
+
+- **`ACMS.Library.tiptap` の中身が入るのはブロックエディターのチャンクがロードされた後**
+  （＝ファクトリが呼ばれる時点）。名前空間の取得自体はいつでもできるが、チャンクロード前に
+  `Node` などへ触ると `ACMS.Library.tiptap.core は…` という例外になる。トップレベルで
+  `import { Node } from '@tiptap/core'` して**即座に使う**コードは書かないこと
+  （静的 import 自体は問題なく、ファクトリの中でしか触らないなら動く）。
+- 公式拡張のバージョンは**本体の tiptap カタログ（`pnpm-workspace.yaml` の `catalogs.tiptap`）に合わせる**。
+  型だけ利用する場合も同じ。
+- 自分で書くカスタムノードはファクトリ引数からも取れる（`registerExtension('x', ({ core }) => core.Node.create(...))`）。
+  externals を設定していない場合はこちらを使う。
+
+
+## 新しい拡張ポイントを追加するときのルール
+
+- イベントを追加する場合は `AcmsEventMap` への module augmentation を、機能の `src/events.ts`
+  （例: `packages/frontend/media/src/events.ts`）等、対象 feature 内に追加する。
+- Slot を追加する場合は `<Slot name="..." fillProps={...} />` を設置し、`fillProps` の型を
+  コンポーネントファイル内で export する（`UnitToolbarSlotFillProps` に倣う）。
+- レジストリを追加する場合は `createRegistry<T>('label')` を `global-singletons.ts` に生やし、
+  `PluginContext` に生えている既存の `unitEditor` / `dataview` ネームスペースに倣って
+  `ctx.{domain}.register{Something}` の形で公開する。
+- 上記いずれの場合も、**本書（`HOOKS.md`）の対応する一覧に追記する**こと。イベントなら
+  「イベント一覧」の対応表に 1 行、Slot なら「Slot 一覧」に 1 行、レジストリなら「レジストリ一覧」に
+  1 行。一度公開したイベント名・Slot 名・レジストリ名は外部プラグインが依存しうるため破壊変更しにくい。
+  本書に載せたものだけを公開 API とみなす（`docs/plan/admin-extensibility-api/tasklist.md`「進め方の注意」）。
+- 詳細は [AGENTS.md](../../../AGENTS.md)「拡張ポイント（フック）の方針」を参照。
+
+## ユースケース実装例: メディア alt の AI 生成ボタン
+
+「メディア詳細モーダルの alt テキストを AI で生成するボタンを足したい」という要望を、Slot・ゲート・
+`withFillProps` の組み合わせで実現する例。Slot を `media-modal.tsx` に 1 箇所（`media.edit-modal.field.alt`）
+置くだけで、MediaModal は共有コンポーネントのため、メディア管理・カスタムフィールド・ブロックエディター
+画像/ファイル・リッチエディター・バナー・ナビゲーション・ユニットの 8 経路すべてに同時に効く。
+
+外部プラグイン（`InjectTemplate::add()` で `<script type="module">` として読み込まれ、npm パッケージを
+import できない環境）が書くコードの例:
+
+```jsx
+// ai-alt-plugin.jsx — InjectTemplate::add() で <script type="module"> として読み込む
+const { withFillProps } = ACMS.plugins;
+
+ACMS.plugins.register('ai-alt-generator', {
+  version: '1.0.0',
+  setup(ctx) {
+    // UI 差し込み: alt 欄の直後に「AI で生成」ボタン
+    ctx.ui.fill('media.edit-modal.field.alt', withFillProps(({ item, previewSrc, setAlt }) => (
+      <button
+        type="button"
+        className="acms-admin-btn"
+        onClick={async () => {
+          const alt = await generateAltByAi(previewSrc, ctx.config.apiEndpoint);
+          setAlt(alt);
+        }}
+      >alt を AI で生成</button>
+    )));
+
+    // 保存前検査: alt 未入力の画像を保存させない（ゲートのキャンセル使用例）
+    ctx.events.on('media.update.before', (payload, gateCtx) => {
+      if (payload.item.media_type === 'image' && !payload.formData.get('field_3')) {
+        gateCtx.cancel('alt テキストを入力してください');
+      }
+    });
+  },
+});
+```
+
+- `withFillProps` の入手経路は `ACMS.plugins.withFillProps`（グローバル公開。上記「`ctx.ui.fill` で
+  fillProps を受け取る」参照）。内部コード（本体・パッケージ）は `import { withFillProps } from
+  '@ablogcms/plugins'` も使える。
+- alt 行は `ACMS.Config.mediaShowAltAndCaptionOnModal` が off のとき行ごと `display:none` になる。Slot も
+  一緒に消える仕様（alt 生成という文脈から離れる置き場所を避けるため、行外には置かない）。
+- `setAlt` は `AutoResizeTextarea` の `setValue`（imperative handle）を呼ぶため、内部 state・DOM 値・
+  高さの自動リサイズがまとめて更新される（「Slot 一覧」の `media.edit-modal.field.alt` 行参照）。
+- 保存前検査（`media.update.before`）でキャンセルする場合は `ctx.cancel()`（理由なし）ではなく
+  `ctx.cancel(reason)`（理由あり）を使うと、`reason` がそのままユーザーへの表示に使われる
+  （`media-modal.tsx` の `update()` が `gateResult.reason` を alert する）。
+- MediaModal はクラスコンポーネントだが、`<Slot>` を render() に置くこと自体は問題ない。Fill 側
+  （プラグイン）は `withFillProps` の制約により関数コンポーネント必須。
+
+## カスタムブロックの作り方
+
+カスタムブロックの実体は「BLOCK_DEFINITIONS 相当のエントリ（type 実装マスター）＋（新規 node/mark
+type の場合のみ）Tiptap 拡張（スキーマ層）」の 2 層。**「どの type をブロックメニューに出すか」は
+今まで通り管理者が編集設定画面（ブロックエディター設定 → ブロックメニュー）で選び、config として
+保存するサーバー駆動のまま**（Gutenberg の `register_block_type()` と同じく「登録＝実装の提供」で
+あって「メニューへの露出」は別の関心事、という設計に倣っている。プラグインは「メニュー登録 API」を
+使わず、type の実装を登録するだけでよい。
+
+### 1. type の実装を登録する（JS）
+
+```tsx
+import type { BlockDefinition } from '@ablogcms/block-editor/types';
+
+ACMS.plugins.register('my-plugin', {
+  setup(ctx) {
+    // (1) スキーマ層（新規 node type の場合のみ。既存 node の組み合わせだけなら不要）
+    ctx.blockEditor.registerExtension('callout', ({ core }) =>
+      core.Node.create({
+        name: 'callout',
+        group: 'block',
+        content: 'paragraph+',
+      })
+    );
+
+    // (2) type 実装マスター（ほぼすべてのカスタムブロックで必須。これが無いと編集設定に
+    //     type を書いてもメニュー解決パイプライン（createBlockMenu / resolveCommands）で捨てられる）
+    ctx.blockEditor.registerBlockDefinition('callout', () => ({
+      label: 'コールアウト',
+      description: '注意書きブロック',
+      icon: 'info',
+      isTextMenu: false,
+      createActions: (cmd) => ({
+        action: (editor) => editor.chain().focus().insertContent({ type: 'callout' }).run(),
+        isDisabled: () => false,
+      }),
+    }));
+  },
+});
+```
+
+`registerBlockDefinition` / `registerExtension` の使い分け・ファクトリが `Tiptap` を受け取る
+理由は「レジストリ一覧」参照。
+
+### 2. 編集設定画面に type の選択肢を追加する（PHP 側の追加実装は不要）
+
+編集設定画面（ブロックエディター設定 → ブロックメニュー）の type セレクトは、コアの type だけを
+`ablogcms/themes/system/admin/config/block-editor.html` にハードコードしている。プラグイン提供の
+type をここに並べるために、**PHP 側でレジストリや Hook を新設する必要はない**。かわりに JS 側
+（`ablogcms/js/src/elements/block-editor-menu-type-select-element.ts`）が、この設定画面を開いた
+タイミングで `registerBlockDefinition` 済みの type を読み出し、「プラグイン」optgroup として
+select に追加する。行の追加（`js-fieldgroup-sortable` の複製）で生成される新しい行にも同じ optgroup
+が反映される（`acmsAddCustomFieldGroup` → `acmsAdminDelayedContents` 経由）。
+
+- 管理者は追加された optgroup からプラグインの type を選び、通常どおり保存するだけでよい。
+- 保存された config 値（`block_editor_block_menu_type` 等）は `ACMS_GET_Admin_BlockEditor_SettingsJson`
+  がバリデーションなしでそのまま返す設計のため（`getBlockMenuSetting()` のコメント参照）、未知の
+  type であっても PHP 側は素通しする。プラグインの type がここで弾かれることはない。
+- **Why not（PHP 側にも type カタログを持たせなかった理由）**: 当初 PHP 側にも
+  `Services/BlockEditor/BlockDefinitionRegistry` のような並行レジストリを試作したが、(1) select の
+  選択肢はラベルさえ分かればよく、ラベルは JS 側の `BlockDefinition.label` に既に存在するため
+  二重管理になる、(2) a-blog cms の管理画面 JS は Gutenberg のように編集画面自体が SPA であり、
+  クライアント側のレジストリを直接列挙できる（`wp.blocks.getBlockTypes()` に相当する構成が既にある）
+  ため、WordPress の「Block Manager」系プラグインのようにサーバー側へ一覧を複製する理由がない。
+  型別カスタムフィールド（type ごとの追加設定項目）の動的レンダリングも同じ理由でスコープ外とし、
+  必要ならプラグイン自身の管理画面（独自のコンフィグ画面・`InjectTemplate::add()`）で提供する方針とする。
+
+### 3. 保存 HTML のサニタイズ
+
+カスタムブロックが出力する独自タグ・属性が既定の HTMLPurifier 許可リストに無い場合、公開側表示や
+保存時に剥がされることがある。必要に応じて PHP Hook `extendsHtmlPurifierDefinition`
+（`Services/HtmlPurifier`）で許可要素・属性を追加すること（[functional-design.md](../../../docs/foundation/functional-design.md)
+「拡張ポイント」参照）。
+
+## ブロックツールバーの拡張
+
+BlockMenu（統合ブロックツールバー。ブロック選択時に出る単一のツールバー。旧 TextMenu /
+ImageBlockMenu 等の並立構成を統合したもの）へ独自のボタン・UI を差し込む経路は、拡張内 `blockMenu`
+宣言と Slot（`block-editor.block-menu` 系）の 2 つがある。**新しいレジストリは増やさない**。
+
+- **拡張内 `blockMenu` 宣言**（推奨）: `ctx.blockEditor.registerExtension` で登録する Tiptap 拡張自身
+  の `addOptions()` に `blockMenu` プロパティを書く。ノード・コマンドを伴う拡張（カスタムブロック等）を
+  作るときはこちらを使う。「拡張の登録」と「ツールバーへの露出」が同じ場所に書けるコロケーション
+  設計で、WordPress Gutenberg が `BlockControls` をブロックの `edit` 実装内に書くのと同じ思想。
+- **Slot**（`block-editor.block-menu` 系。「Slot 一覧」参照）: 新しい拡張・ノードを伴わず、UI だけを
+  差し込みたい場合に使う低レベル経路。既存の拡張には手を入れられない・触れたくない場合や、ブロック
+  種別に依存しない汎用ツールを差し込みたい場合に向く。
+
+どちらの経路で追加した項目も、見た目・並び（共通区画が先、種別別区画が後）は同じツールバーの中に
+混在して表示される。なお、a-blog cms 本体のブロック種別セクション（画像・ファイル・リンクボタン・
+テーブル・テキスト書式）も同じ「拡張内 `blockMenu` 宣言」で登録してある（`ImageBlock` /
+`FileBlock` / `LinkButton` / `Table` / `TextFormat` 拡張）。BlockMenu 側にブロック種別ごとの分岐は
+無く、コアもプラグインも同じ経路で区画を組み立てる。
+
+### blockMenu 宣言の形
+
+`blockMenu` は 2 種類の宣言を配列で混在できる（型は `@ablogcms/block-editor/types` の
+`BlockMenuToolbarItem` = `BlockMenuButtonItem | BlockMenuRenderItem`）。
+
+- **データ型**（`BlockMenuButtonItem`）: `icon`（Material Symbols 名）/ `tooltip` / `onSelect` を持つ
+  プレーンなオブジェクト。React を持ち込まずに済み、既存の `Toolbar.Button` + `Icon` で描画される。
+  `isActive` / `isDisabled` はトランザクションのたびに再評価される。
+- **コンポーネント型**（`BlockMenuRenderItem`）: `render({ editor, variant })` が任意の `ReactNode` を
+  返す。`Toolbar.Button` の枠に収まらない UI（複数ボタンの組み合わせ、ポップオーバー付きメニュー等）
+  向け。`scope`/`order` は `render` を実行しなくても判定できるプレーンなデータとして持つため、
+  対象外の区画では `render` は一度も呼ばれない。
+
+両方とも共通のメタ情報を持つ。
+
+- `scope?: BlockMenuItemScope | BlockMenuItemScope[]`（`'common' | 'text' | 'image' | 'file' |
+  'linkButton' | 'table' | (任意のノード名)`）: 表示する区画。固定の区画名に加えて、**スキーマに
+  存在する任意のノード名**をそのまま指定できる（`BlockMenuItemScope` は LiteralUnion パターン。
+  組み込み値の補完を保ちつつ任意の string も受け付ける）。ノード名を指定した場合、「現在選択中の
+  ブロックがそのノードか」を `editor.isActive(nodeName)`（NodeSelection・カーソル位置どちらでも
+  機能する）で直接判定して表示可否を決める。`image`/`file`/`linkButton`/`table`/`text` の 5 つだけは
+  `resolveBlockMenuState` が解決する固定 variant とそのまま比較する（後方互換の判定経路）。
+  **省略時は宣言元の拡張から自動判定**する。拡張が Node で
+  `imageBlock`/`fileBlock`/`linkButton`/`table` のいずれかに対応するノード名ならその区画、テキスト
+  ブロック相当のノード（`isTextblock`）なら `'text'`、**それ以外の Node（独自ノードを含む）は
+  自ノード名**になる（＝ノード名を明示したときと同じ「そのノード選択時のみ表示」になる）。
+  Mark・Extension（Node ではない拡張）は `'common'` になる。`'common'` を他の値と併記した場合、
+  他の値の有無に関わらず常に共通区画に表示される（variant 別区画に二重表示されることはない）。
+  ノード名スコープの項目には専用の区画コンポーネントが無いため、描画位置は共通区画と同じ位置に
+  なる（区画内の並び順は `order` がそのまま効く）。
+- `order?: number`: 同一区画内での並び順（既定 `0`。小さいほど先。同値は宣言順を維持）。コアの
+  ブロック種別セクションは `-100`（`CORE_BLOCK_MENU_SECTION_ORDER`）で宣言されているため、既定値の
+  ままならプラグインの項目はセクションの後ろに並ぶ。セクションより前に出したい場合は `-100` より
+  小さい値を指定する。
+
+不正な宣言（`blockMenu` が配列でない、データ型/コンポーネント型どちらの形にも一致しない、`scope` が
+既知の値でもスキーマ上のノード名でもない等）はその項目だけを無視し、`console.warn` で該当拡張名を
+出す。1 つのプラグインの記述ミスでエディタ全体が落ちないよう、例外は投げない。
+
+### コード例（データ型）
+
+「カスタムブロックの作り方」の `callout` 拡張に、太字化ボタンを追加する例。
+
+```tsx
+ACMS.plugins.register('my-plugin', {
+  setup(ctx) {
+    ctx.blockEditor.registerExtension('callout', ({ core }) =>
+      core.Node.create({
+        name: 'callout',
+        group: 'block',
+        content: 'paragraph+',
+        addOptions() {
+          return {
+            blockMenu: [
+              {
+                icon: 'format_bold',
+                tooltip: '強調表示に切り替え',
+                isActive: (editor) => editor.isActive('callout', { emphasis: true }),
+                onSelect: (editor) => editor.chain().focus().updateAttributes('callout', { emphasis: true }).run(),
+                // scope 省略時は Node 名 'callout' から自動判定される。callout は
+                // imageBlock/fileBlock/linkButton/table のいずれでもなく isTextblock でもないため、
+                // 自ノード名 'callout' にフォールバックする。つまりこのボタンは「callout ブロックを
+                // 選択している間だけ」表示され、他のブロックを選んでいるときは出ない
+                // （描画位置自体は専用区画が無いため共通区画と同じ位置になる）。
+              },
+            ],
+          };
+        },
+      })
+    );
+  },
+});
+```
+
+### コード例（独自ノードへの明示的なスコープ指定）
+
+上の例は `scope` 省略時のフォールバックで暗黙的に `callout` へスコープされているが、
+明示的にノード名を書いても同じ結果になる。複数のノードに同時対応させたい場合など、
+フォールバックだけでは表現できないケースで使う。
+
+```tsx
+addOptions() {
+  return {
+    blockMenu: [
+      {
+        icon: 'format_bold',
+        tooltip: '強調表示に切り替え',
+        // 'callout' と 'anotherCustomNode' のどちらを選択しているときも表示する
+        scope: ['callout', 'anotherCustomNode'],
+        isActive: (editor) => editor.isActive('callout', { emphasis: true }),
+        onSelect: (editor) => editor.chain().focus().updateAttributes('callout', { emphasis: true }).run(),
+      },
+    ],
+  };
+},
+```
+
+### コード例（コンポーネント型）
+
+```tsx
+import type { BlockMenuRenderItem } from '@ablogcms/block-editor/types';
+
+ctx.blockEditor.registerExtension('callout', ({ core }) =>
+  core.Node.create({
+    name: 'callout',
+    group: 'block',
+    content: 'paragraph+',
+    addOptions() {
+      return {
+        blockMenu: [
+          {
+            scope: 'common',
+            render: ({ editor }) => (
+              <select onChange={(e) => editor.chain().focus().updateAttributes('callout', { level: e.target.value }).run()}>
+                <option value="info">情報</option>
+                <option value="warning">警告</option>
+              </select>
+            ),
+          } satisfies BlockMenuRenderItem,
+        ],
+      };
+    },
+  })
+);
+```
+
+### コード例（Slot。UI だけを差し込みたい場合）
+
+```tsx
+import { withFillProps } from '@ablogcms/plugins';
+import type { BlockMenuSlotFillProps } from '@ablogcms/block-editor/block-menu';
+
+ACMS.plugins.register('my-plugin', {
+  setup(ctx) {
+    // 画像ブロックがアクティブなときだけ表示される独自ボタン（新しい拡張・ノードは伴わない）
+    ctx.ui.fill(
+      'block-editor.block-menu.image',
+      withFillProps<BlockMenuSlotFillProps>(({ editor }) => (
+        <button type="button" onClick={() => alert('画像を検査')}>
+          画像を検査
+        </button>
+      ))
+    );
+  },
+});
+```
+
+## カスタムユニットの作り方
+
+ユニットエディター側も「編集設定（サーバー）でメニュー露出 + `ctx.unitEditor.registerUnitDefinition`
+（JS レジストリ）で描画」というブロックエディターと同じ分業を取る（レジストリ一覧参照）。ただし
+ユニットは「保存データ構造を持つ実体」（`column_type` ごとの PHP Unit Model）を必ず伴う点がブロック
+エディター（コンテンツは HTML/JSON としてそのまま保存され、PHP 側は基本サニタイズのみ）と異なる。
+そのため、プラグインが完全に新しい type を作るか、既存の仕組みに乗るかで手順が変わる。
+
+### 方式A: 独自の保存データ構造を持つユニットを追加する（JS UI + PHP Model の両方が必要）
+
+1. JS 側（描画・編集 UI）は `ctx.unitEditor.registerUnitDefinition('my-chart', unitDef)` で登録する。
+   `unit-editor` / `inplace-editor` / `config-editor` の3経路すべてに配線済み
+   （`unit-definitions.ts` の `getUnitDefinitions()`）ため、この登録だけで3画面に反映される。
+   **type 名にアンダースコア（`_`）を含めないこと**。PHP `detectUnitTypeSpecifier()`
+   （`ACMS/function.php`）と JS `UnitFactory#resolveName`（`core/factory.ts`）が共に
+   `_` より前だけを実際の type として扱う仕様（同一 type の派生バリアントを
+   `type_variant` のように区別する既存の仕組み）のため、`my_chart` は `my` として解決され
+   意図せず衝突・分断する。ハイフン区切り（`my-chart`）を使う。
+2. PHP 側（保存・読み込み・公開側レンダリング）は、`Acms\Services\Unit\Registry`（`unit-registry`
+   サービス）が `column_type` 文字列とモデルクラスを対応付けて解決する。この対応表に無い type は
+   `Acms\Services\Unit\Repository::makeModel()` が `null` を返して**例外もログもなく黙って捨てる**
+   （保存 POST・DB からの読み込み・公開側レンダリングで共通の契約。`extractUnits()` は
+   `continue`、`loadModels()` は `array_filter` で除外）ため、PHP 側の bind を忘れると
+   「保存したはずのユニットが消える」という気づきにくい形で失敗する。拡張アプリの
+   ServiceProvider から次のように登録する（コア標準 type も `UnitServiceProvider::init()` が同じ
+   仕組みで登録している）。
+
+   ```php
+   use Acms\Services\Facades\Application;
+   use Acms\Services\Unit\Registry;
+
+   Application::bootstrap('unit-registry', function (Registry $registry) {
+       $registry->bind('my-chart', \Acms\Plugins\MyPlugin\Unit\MyChart::class);
+   });
+   ```
+
+   `MyChart` クラスは `Acms\Services\Unit\Contracts\Model` を実装する（`render` / `renderEdit` /
+   `extract` / `canSave` など。既存モデル `ablogcms/php/Services/Unit/Models/*.php` が実装例）。
+   Hook のような新しい仕組みは不要で、`Application::bootstrap()` という既存のコンテナ機構
+   （`Services/Container.php`）だけで完結する（動作は
+   `tests/phpunit/Unit/Services/Unit/RegistryTest.php` の特徴付けテストで固定済み）。
+   このコールバックは `Application::make('unit-registry')` が呼ばれるたびに再実行される設計
+   （キャッシュされるのはインスタンスのみ）のため、`bind()` のような冪等な呼び出しに留め、
+   副作用を持つ処理（カウントアップ・外部通信等）をここに書かないこと。
+3. 編集設定への type 追加は PHP 側の追加実装が不要。ユニット追加メニューの構成
+   （`ablogcms/themes/system/admin/config/edit.html` の `column_add_type[]`）はブロックエディターの
+   `<select>` と異なり、自由テキスト入力（`<input list="column_add_type">` + `<datalist>` サジェスト）
+   のため、管理者は `my-chart` をそのまま入力して保存できる。datalist のサジェスト候補
+   （`ACMS_GET_Admin_Unit_ModelOptions` → `Registry::getOptions()`）は2.で bind した type から自動的に
+   列挙されるため、ここでも追加の PHP 実装は不要。
+
+### 方式B: 既存の `custom`（カスタムユニット）に乗る（PHP Model 実装が不要）
+
+独自の React UI が不要で、フィールドの組み合わせで十分な場合は、コア標準の `custom` type
+（`Acms\Services\Unit\Models\Custom`、Field ベースの汎用データストア）をそのまま使う方が軽い。
+この場合 PHP Model の新規実装は不要（`custom` は既にコアで `unit-registry` に bind 済み）。
+JS 側の描画も `registerUnitDefinition('custom', unitDef)` で上書き可能（`unitDefs` は
+`{ ...coreUnitDefs, ...registryUnitDefs }` という後勝ちのマージのため、組み込みの `custom`
+UnitDef をプラグインの React コンポーネントに差し替えられる）が、**この上書きはそのブログの
+全 `custom` ユニットに一律で効く**（`custom_foo` のような specifier 付き type も
+`detectUnitTypeSpecifier()` で `custom` に丸められるため、特定プラグイン専用の `custom` だけを
+差し替えることはできない）。プラグイン専用の見た目・挙動が必要な場合は方式A を使う。
+
+### ツールバー拡張
+
+ユニットエディターのツールバーへの UI 差し込みは既存の Slot `unit-editor.unit-toolbar` を使う
+（Slot 一覧参照）。