ampless 1.0.0-alpha.43 → 1.0.0-alpha.44

package/dist/index.d.ts

@@ -862,6 +862,16 @@ interface PluginPackageManifest {
     description?: LocalizedString;
     /** Optional docs / repo URL. */
     homepage?: string;
+    /**
+     * Subpath (relative to the plugin's package.json) of the editor
+     * module to auto-wire. `update-ampless` reads this to regenerate
+     * `app/(admin)/admin/_editor-bootstrap.tsx`. Absent = no editor
+     * extension (= plugin doesn't ship a tiptap Node).
+     *
+     * The referenced module must export `editorExtension` as a named
+     * symbol of type tiptap Extension.
+     */
+    editorExports?: string;
 }
 /**
  * Secret field types for `settings.secret`. Restricted to `text` /

package/docs/plugin-author-guide.ja.md

@@ -777,25 +777,67 @@ runtime は `src` のホスト allowlist を強制しない。CSP はサイト
 
 ## 6d. Admin エディタ拡張の配線 (Phase 7)
 
-admin エディタに tiptap Node 拡張を提供するプラグインは、別途 `./editor` subpath の client-side エントリを出荷する。テンプレート側で `_editor-bootstrap.tsx` から配線する:
+admin エディタに tiptap Node 拡張を提供するプラグインは、別途 `./editor` subpath の client-side エントリを出荷する。
+`app/(admin)/admin/_editor-bootstrap.tsx` は `npm run update-ampless` によって**自動生成**される — 手動で編集してはならない。
+
+### プラグイン著者向け
+
+`package.json#amplessPlugin` に `editorExports` を宣言する:
+
+```jsonc
+// packages/plugin-youtube/package.json
+"amplessPlugin": {
+  "apiVersion": 1,
+  "name": "youtube",
+  "trustLevel": "trusted",
+  "capabilities": ["contentFields"],
+  "editorExports": "./editor"   // ← editor module のある subpath
+}
+```
+
+その subpath から `editorExtension` を named export する:
+
+```ts
+// packages/plugin-youtube/src/editor.tsx
+export const editorExtension = AmplessYoutubeNode   // tiptap Node または Extension
+```
+
+`package.json#exports` にも同 subpath を宣言すること（codegen がこれを検証する — 未宣言の場合は warning を出してそのプラグインをスキップする）:
+
+```jsonc
+"exports": {
+  ".":       { "import": "./dist/index.js", "types": "./dist/index.d.ts" },
+  "./editor": { "import": "./dist/editor.js", "types": "./dist/editor.d.ts" }
+}
+```
+
+### プラグインユーザー（サイトエンジニア）向け
+
+1. `npm i @ampless/plugin-youtube@alpha` — plugin を dependency として追加する。
+2. `cms.config.ts` に登録してサーバーサイド renderer を有効化する。
+3. `npm run update-ampless` — インストール済み plugin の manifest から `_editor-bootstrap.tsx` を自動再生成する。
+
+生成されたファイルはリポジトリにコミットされ、以下のような内容になる:
 
 ```tsx
-// templates/_shared/app/(admin)/admin/_editor-bootstrap.tsx
+// app/(admin)/admin/_editor-bootstrap.tsx  (AUTO-GENERATED — 編集不可)
 'use client'
+// AUTO-GENERATED by `npm run update-ampless`. Do not edit — your changes
+// will be overwritten on the next run.
 import { installAdminEditorExtensions } from '@ampless/admin/editor'
-import { youtubeEditor } from '@ampless/plugin-youtube/editor'
-import { tweetEditor } from '@ampless/plugin-x-embed/editor'
+import { editorExtension as __ampless_plugin_x_embed_editor } from '@ampless/plugin-x-embed/editor'
+import { editorExtension as __ampless_plugin_youtube_editor } from '@ampless/plugin-youtube/editor'
 
 export function EditorBootstrap({ children }: { children: React.ReactNode }) {
   installAdminEditorExtensions([
-    youtubeEditor.extension,
-    tweetEditor.extension,
+    __ampless_plugin_x_embed_editor,
+    __ampless_plugin_youtube_editor,
   ])
   return <>{children}</>
 }
 ```
 
-その上で layout に渡す:
+このファイルは admin layout に渡される（テンプレートに既に組み込まれているので追加の作業は不要）:
 
 ```tsx
 // templates/_shared/app/(admin)/admin/layout.tsx
@@ -806,6 +848,13 @@ export default createAdminLayout(admin, { editorBootstrap: EditorBootstrap })
 
 `installAdminEditorExtensions` は idempotent で、render 時に client component 内で呼ばれる。admin の `<TiptapEditor>` は毎回 render 時に登録済みリストを built-in extensions の末尾に spread する。
 
+### active source と完全無効化
+
+**エディタ配線の active source は `package.json#dependencies`**（= `node_modules`）であり、`cms.config.ts` ではない。
+
+- plugin を `cms.config.ts` から外しても `package.json` に dep が残っていれば、editor の paste rule は**有効のまま**になる。editor は tiptap document にそのノード型を挿入できるが、公開 renderer はレンダリングしない（不整合状態 — 避けること）。
+- 完全に無効化するには: `cms.config.ts` から削除 **かつ** `npm uninstall @ampless/plugin-...` を実行し、`npm run update-ampless` で bootstrap ファイルを再生成する。
+
 ### エディタプレビューのパイプライン
 
 admin の edit / new post フォームは preview ペインを `<iframe sandbox="allow-scripts">` で表示する。`srcDoc` はテンプレート側 preview Route Handler が返す HTML。テンプレート scaffold は handler を `app/(admin)/admin/preview/route.tsx` に同梱する:

package/docs/plugin-author-guide.md

@@ -1026,26 +1026,72 @@ middleware. This is documented in each plugin's README.
 ## 6d. Admin editor extension wiring (Phase 7)
 
 Plugins that contribute tiptap Node extensions to the admin editor
-ship a separate client-side entry under the `./editor` subpath. The
-template wires it up in `_editor-bootstrap.tsx`:
+ship a separate client-side entry under the `./editor` subpath.
+`app/(admin)/admin/_editor-bootstrap.tsx` is **auto-generated** by
+`npm run update-ampless` — you should not edit it by hand.
+
+### For plugin authors
+
+Declare `editorExports` in `package.json#amplessPlugin`:
+
+```jsonc
+// packages/plugin-youtube/package.json
+"amplessPlugin": {
+  "apiVersion": 1,
+  "name": "youtube",
+  "trustLevel": "trusted",
+  "capabilities": ["contentFields"],
+  "editorExports": "./editor"   // ← subpath where the editor module lives
+}
+```
+
+Export `editorExtension` as a named symbol from that subpath:
+
+```ts
+// packages/plugin-youtube/src/editor.tsx
+export const editorExtension = AmplessYoutubeNode   // tiptap Node or Extension
+```
+
+The subpath must be declared in `package.json#exports` as well (the
+codegen validates this — a missing `exports` entry triggers a warning
+and the plugin is skipped):
+
+```jsonc
+"exports": {
+  ".":       { "import": "./dist/index.js", "types": "./dist/index.d.ts" },
+  "./editor": { "import": "./dist/editor.js", "types": "./dist/editor.d.ts" }
+}
+```
+
+### For plugin users (site engineers)
+
+1. `npm i @ampless/plugin-youtube@alpha` — add the plugin as a dependency.
+2. Register it in `cms.config.ts` for the server-side renderer.
+3. `npm run update-ampless` — regenerates `_editor-bootstrap.tsx`
+   automatically from the installed plugin manifests.
+
+The generated file is committed to your repo and looks like:
 
 ```tsx
-// templates/_shared/app/(admin)/admin/_editor-bootstrap.tsx
+// app/(admin)/admin/_editor-bootstrap.tsx  (AUTO-GENERATED — do not edit)
 'use client'
+// AUTO-GENERATED by `npm run update-ampless`. Do not edit — your changes
+// will be overwritten on the next run.
 import { installAdminEditorExtensions } from '@ampless/admin/editor'
-import { youtubeEditor } from '@ampless/plugin-youtube/editor'
-import { tweetEditor } from '@ampless/plugin-x-embed/editor'
+import { editorExtension as __ampless_plugin_x_embed_editor } from '@ampless/plugin-x-embed/editor'
+import { editorExtension as __ampless_plugin_youtube_editor } from '@ampless/plugin-youtube/editor'
 
 export function EditorBootstrap({ children }: { children: React.ReactNode }) {
   installAdminEditorExtensions([
-    youtubeEditor.extension,
-    tweetEditor.extension,
+    __ampless_plugin_x_embed_editor,
+    __ampless_plugin_youtube_editor,
   ])
   return <>{children}</>
 }
 ```
 
-Then thread it into the layout:
+The file is then wired into the admin layout (already in the template — no
+extra work required):
 
 ```tsx
 // templates/_shared/app/(admin)/admin/layout.tsx
@@ -1058,6 +1104,19 @@ export default createAdminLayout(admin, { editorBootstrap: EditorBootstrap })
 inside a client component. The admin's `<TiptapEditor>` spreads the
 registered list onto its built-in extensions on every render.
 
+### Active source and full disable
+
+**The active source for editor wiring is `package.json#dependencies`**
+(= `node_modules`), not `cms.config.ts`. This means:
+
+- Removing a plugin from `cms.config.ts` but keeping it in
+  `package.json` leaves the editor paste rule active. The editor can
+  still insert the node type into the tiptap document, but the public
+  renderer won't render it (inconsistent state — avoid).
+- To fully disable a plugin's editor extension: remove it from
+  `cms.config.ts` **and** run `npm uninstall @ampless/plugin-...`,
+  then `npm run update-ampless` to regenerate the bootstrap file.
+
 ### Editor preview pipeline
 
 The admin's edit / new post forms render the preview pane in an

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ampless",
-  "version": "1.0.0-alpha.43",
+  "version": "1.0.0-alpha.44",
   "description": "Serverless CMS for AWS Amplify",
   "license": "MIT",
   "type": "module",