ampless 1.0.0-alpha.43 → 1.0.0-alpha.45

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` /
@@ -989,6 +999,21 @@ interface TiptapRenderNode {
     }[];
     text?: string;
 }
+/**
+ * Adapter that converts a single tiptap node back to its markdown form.
+ * Plugins that ship an embed node (e.g. amplessYoutube → bare YouTube URL)
+ * export a map from nodeType to adapter from their `./editor` module
+ * (named export `tiptapNodeToMarkdown`); `update-ampless` wires the map
+ * into `installAdminTiptapNodeMarkdown` so the admin's
+ * `tiptap → markdown` format switch can losslessly serialise the embed
+ * (the round-trip back to tiptap goes through markdown's bare-URL paste
+ * rule + `extractSingleUrl` in the runtime).
+ *
+ * Return `null` (or simply omit the nodeType from the map) to fall
+ * through to the runtime's default markdown switch.
+ */
+type TiptapNodeToMarkdown = (node: TiptapRenderNode) => string | null;
+type TiptapNodeMarkdownAdapters = Readonly<Record<string, TiptapNodeToMarkdown>>;
 /**
  * Match object passed to a `contentFields` `markdown-url` renderer. The
  * runtime walks the markdown body via `marked.lexer`, tests the trimmed
@@ -1876,4 +1901,4 @@ declare function pickDefaultEntrypoint(files: readonly {
 
 declare const VERSION = "0.0.1";
 
-export { type AmplessEvent, type AmplessPlugin, type AuthContext, type BundleExtractResult, type CacheConfig, type CacheStrategy, type Config, type ContentEventPayload, type ContentEventType, type ContentFieldRenderer, type ContentFormat, type ContentTypeDefinition, type CreatePostInput, DEFAULT_ENTRYPOINT, type DateFormat, type EventPayloadOf, type EventType, type ExtractedFile, type FieldDefinition, type FieldType, type HistoryConfig, type ImageDisplay, type KvItem, type KvStore, type LinkListItem, type ListOptions, type ListPostHistoryOptions, type LocalizedString, MAX_BUNDLE_BYTES, type MarkdownEmbedMatch, type Media, type MediaEventPayload, type MediaEventType, type MediaMetadata, type MediaProcessingDefaults, type OgImageConfig, type OgImageFont, type OgImageRenderContext, PLUGIN_KEY_PATTERN, type Page, type PluginBooleanField, type PluginCapability, type PluginCodeField, type PluginEventHandler, type PluginHookResult, type PluginJsonField, type PluginMetadata, type PluginNumberField, type PluginPackageManifest, type PluginPublicRenderContext, type PluginRepeatableField, type PluginRepeatableSubField, type PluginRuntimeContext, type PluginSecretField, type PluginSelectField, type PluginSettingField, type PluginSettingsManifest, type PluginTextField, type PluginTextareaField, type PluginUninstallContext, type PluginUrlField, type Post, type PostIndexEventPayload, type PostIndexEventType, type PostMetadata, type PostRevision, type PostRevisionConnection, type PostStatus, type PostsProvider, type PublicBodyDescriptor, type PublicHeadDescriptor, type PublicPostBodyDescriptor, type PublicPostHtmlDescriptor, type PublicPostHtmlPosition, type PublicPostScriptDescriptor, type Role, SITE_CONFIG_PK, type ScriptStrategy, type SiteSettingsEventPayload, type SiteSettingsEventType, type StaticPostBody, type StaticPostFileMeta, type StreamEventName, TEXT_EXTENSIONS, type ThemeColorField, type ThemeField, type ThemeFieldType, type ThemeFontFamilyField, type ThemeImageField, type ThemeLengthField, type ThemeLinkListField, type ThemeManifest, type ThemeModule, type ThemeRouteContext, type ThemeSelectField, type ThemeTextField, type TiptapRenderNode, type TrustLevel, type TrustedPluginRuntimeContext, VERSION, type ValidationIssue, bundlePrefix, createPost, decodeAwsJson, defineConfig, definePlugin, defineSchema, defineTheme, defineThemeModule, deletePost, deleteSiteSetting, detectContentEvents, encodeAwsJson, escapeXml, extractFirstImageUrl, findAbsolutePathRefs, flattenSettings, formatColorPair, formatDate, formatPublicAssetUrl, getKvStore, getPost, getPostById, getSiteSetting, hasKvStore, hasPostsProvider, isTagListUrl, isValidPluginKey, listPostHistory, listPosts, listSiteSettings, mimeTypeFor, parseColorPair, parseLinkList, pickDefaultEntrypoint, resolveLocalized, resolvePluginSettings, resolveThemeValues, setKvStore, setPostsProvider, setSiteSetting, stringifyLinkList, stripCommonPrefix, themeSettingKey, unflattenSettings, updatePost, validateBundle, validateBundlePath, validatePluginSettingValue, validatePublicAssetKey, validateThemeValue };
+export { type AmplessEvent, type AmplessPlugin, type AuthContext, type BundleExtractResult, type CacheConfig, type CacheStrategy, type Config, type ContentEventPayload, type ContentEventType, type ContentFieldRenderer, type ContentFormat, type ContentTypeDefinition, type CreatePostInput, DEFAULT_ENTRYPOINT, type DateFormat, type EventPayloadOf, type EventType, type ExtractedFile, type FieldDefinition, type FieldType, type HistoryConfig, type ImageDisplay, type KvItem, type KvStore, type LinkListItem, type ListOptions, type ListPostHistoryOptions, type LocalizedString, MAX_BUNDLE_BYTES, type MarkdownEmbedMatch, type Media, type MediaEventPayload, type MediaEventType, type MediaMetadata, type MediaProcessingDefaults, type OgImageConfig, type OgImageFont, type OgImageRenderContext, PLUGIN_KEY_PATTERN, type Page, type PluginBooleanField, type PluginCapability, type PluginCodeField, type PluginEventHandler, type PluginHookResult, type PluginJsonField, type PluginMetadata, type PluginNumberField, type PluginPackageManifest, type PluginPublicRenderContext, type PluginRepeatableField, type PluginRepeatableSubField, type PluginRuntimeContext, type PluginSecretField, type PluginSelectField, type PluginSettingField, type PluginSettingsManifest, type PluginTextField, type PluginTextareaField, type PluginUninstallContext, type PluginUrlField, type Post, type PostIndexEventPayload, type PostIndexEventType, type PostMetadata, type PostRevision, type PostRevisionConnection, type PostStatus, type PostsProvider, type PublicBodyDescriptor, type PublicHeadDescriptor, type PublicPostBodyDescriptor, type PublicPostHtmlDescriptor, type PublicPostHtmlPosition, type PublicPostScriptDescriptor, type Role, SITE_CONFIG_PK, type ScriptStrategy, type SiteSettingsEventPayload, type SiteSettingsEventType, type StaticPostBody, type StaticPostFileMeta, type StreamEventName, TEXT_EXTENSIONS, type ThemeColorField, type ThemeField, type ThemeFieldType, type ThemeFontFamilyField, type ThemeImageField, type ThemeLengthField, type ThemeLinkListField, type ThemeManifest, type ThemeModule, type ThemeRouteContext, type ThemeSelectField, type ThemeTextField, type TiptapNodeMarkdownAdapters, type TiptapNodeToMarkdown, type TiptapRenderNode, type TrustLevel, type TrustedPluginRuntimeContext, VERSION, type ValidationIssue, bundlePrefix, createPost, decodeAwsJson, defineConfig, definePlugin, defineSchema, defineTheme, defineThemeModule, deletePost, deleteSiteSetting, detectContentEvents, encodeAwsJson, escapeXml, extractFirstImageUrl, findAbsolutePathRefs, flattenSettings, formatColorPair, formatDate, formatPublicAssetUrl, getKvStore, getPost, getPostById, getSiteSetting, hasKvStore, hasPostsProvider, isTagListUrl, isValidPluginKey, listPostHistory, listPosts, listSiteSettings, mimeTypeFor, parseColorPair, parseLinkList, pickDefaultEntrypoint, resolveLocalized, resolvePluginSettings, resolveThemeValues, setKvStore, setPostsProvider, setSiteSetting, stringifyLinkList, stripCommonPrefix, themeSettingKey, unflattenSettings, updatePost, validateBundle, validateBundlePath, validatePluginSettingValue, validatePublicAssetKey, validateThemeValue };

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,9 +848,16 @@ 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` に同梱する:
+admin の edit / new post フォームは preview ペインを `<iframe sandbox="allow-scripts allow-same-origin">` で表示する。`srcDoc` はテンプレート側 preview Route Handler が返す HTML。テンプレート scaffold は handler を `app/(admin)/admin/preview/route.tsx` に同梱する:
 
 ```tsx
 // templates/_shared/app/(admin)/admin/preview/route.tsx
@@ -862,7 +911,9 @@ export default createEditPostPage(admin, { previewEndpoint: '/cms/admin/preview'
 
 Server Action ではなく Route Handler を採用した理由: `'use server'` モジュール内部で `react-dom/server` 由来の rendering を行うと、Next.js 15+ が edit-post page の compile に失敗する。build 時に Client Component から Server Action モジュール経由で import graph を辿るため、その経路上で `react-dom/server` に到達した時点で「You're importing a component that imports react-dom/server」チェックが発火する。Route Handler に切り出すことで rendering を import graph から完全に切り離せる — `<PostForm>` は plain な HTTP endpoint を fetch するだけで、bundler は form から handler 側へ踏み込まない。さらに handler 自身が `admin.isEditor()` を明示的にチェックすることで、将来 `(admin)` route-group gate が誤設定された場合の安全側のフェールセーフになる。`react-dom/server` の import 自体を dynamic にしているのは Next.js 16 の Turbopack が、Route Handler を含む app router build 経路で reach できる top-level の `react-dom/server` static import を一律で flag するため。request 時に解決することで build-time import-graph walker から外しつつ、runtime では同じ Node.js subpath からロードする。
 
-iframe の `sandbox="allow-scripts"` は `allow-same-origin` を含まないので、preview の中身は opaque origin で動作する → widget script は admin の DOM に触れない。トレードオフ: widget が自身の origin の storage にアクセスできない場合に正しく動かない可能性がある。Phase 7 時点の dogfood では YouTube iframe / x.com widgets.js とも opaque origin で動作することを確認済み。将来 non-opaque origin が必要な widget が出てきた場合、escape hatch は別 subdomain の preview route + 適切な CSP — sandbox flag を緩めるのは取らない。
+**Preview iframe sandbox — v1 trust boundary 拡張:** iframe は `sandbox="allow-scripts allow-same-origin"` を使う。`srcDoc` とともに使用すると iframe は admin の origin を継承し、サードパーティ embed widget（YouTube SDK、x.com `widgets.js`）が動作できるようになる — opaque-origin（`allow-scripts` のみ）の iframe では動作を拒否する（非 HttpOnly storage / cache へのアクセスと real-origin requests が必要なため）。同時に same-origin により preview スクリプトは admin の auth state / 非 HttpOnly storage / DOM へのアクセスと authenticated same-origin XHR / fetch の発行が可能になる。
+
+これは単なる sandbox 緩和ではなく、**v1 の明示的な設計判断**です: **ampless v1 は admin preview content / plugin script を全部 trusted とみなす**。エンジニアは npm install 前に plugin を審査するし（カスタマイズベース CMS モデル）、body content はこのサイトの trusted editor が作成する。`<PostHistoryPanel>` では別の editor が作成した過去 revision（revision author ≠ preview viewer）をプレビューするケースも通常発生するが、v1 ではそれも明示的に trust ring 内と位置づける。より安全な代替案（別 origin preview route + CSP / COEP / COOP）は v2.0+ でリアルなプラグインマーケットプレイスが必要になった場合に再検討する。
 
 ---
 

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,10 +1104,23 @@ 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
-`<iframe sandbox="allow-scripts">` whose `srcDoc` is the HTML returned
+`<iframe sandbox="allow-scripts allow-same-origin">` whose `srcDoc` is the HTML returned
 by the template's preview Route Handler. The template scaffold ships
 the handler at `app/(admin)/admin/preview/route.tsx`:
 
@@ -1136,14 +1195,24 @@ included; deferring it to request time keeps the module outside the
 build-time import-graph walker while still loading it from the same
 Node.js subpath at runtime.
 
-The iframe's `sandbox="allow-scripts"` (without `allow-same-origin`)
-keeps preview content in an opaque origin so widget scripts cannot
-reach the admin's DOM. The trade-off is that some widgets may misbehave
-when they can't access their own origin's storage; the YouTube iframe
-embed and x.com widgets.js both work under these constraints in
-dogfood as of Phase 7. If a future widget needs a non-opaque preview
-origin, the escape hatch is a separate preview route on a different
-subdomain with appropriate CSP — not relaxing the sandbox flag.
+**Preview iframe sandbox — v1 trust boundary expansion:** The iframe uses
+`sandbox="allow-scripts allow-same-origin"`. With `srcDoc`, this gives
+the iframe the admin's origin, which 3rd-party embed widgets (YouTube SDK,
+x.com `widgets.js`) require — they refuse to initialise in an opaque-origin
+(`allow-scripts`-only) iframe because they need access to non-HttpOnly
+storage / cache and real-origin requests. Same-origin also gives the
+preview script access to the admin's auth state / non-HttpOnly storage /
+DOM and lets it issue authenticated same-origin XHR / fetch.
+
+This is an explicit v1 design decision, not a no-op sandbox relax:
+**ampless v1 treats admin preview content / plugin script as trusted**.
+The engineer audits plugins before npm-installing them (customization-based
+CMS model), and body content is produced by trusted editors of this site.
+`<PostHistoryPanel>` can also surface a past revision authored by a
+different editor (revision author ≠ preview viewer) — v1 explicitly puts
+both inside the trust ring. The safer alternative — separate-origin preview
+route + CSP / COEP / COOP — is parked for v2.0+ if/when a real plugin
+marketplace lands.
 
 ---
 

package/package.json

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