ampless 1.0.0-alpha.40 → 1.0.0-alpha.42

package/dist/index.d.ts

@@ -1,3 +1,5 @@
+import { ReactNode } from 'react';
+
 type ContentEventType = 'content.created' | 'content.updated' | 'content.published' | 'content.unpublished' | 'content.deleted';
 type MediaEventType = 'media.uploaded' | 'media.deleted';
 type SiteSettingsEventType = 'site.settings.updated';
@@ -302,7 +304,7 @@ type TrustLevel = 'untrusted' | 'trusted' | 'privileged';
  * capability today is harmless, but the runtime won't expose any new
  * surface for it until the matching phase ships.
  */
-type PluginCapability = 'publicHead' | 'publicBody' | 'metadata' | 'eventHooks' | 'adminSettings' | 'writePublicAsset' | 'schema' | 'publicHtmlForPost' | 'secretSettings' | 'contentFields' | 'adminPage' | 'serverRoute' | 'network' | 'scheduler' | 'storageWrite' | 'privilegedSystem' | 'cspReady';
+type PluginCapability = 'publicHead' | 'publicBody' | 'metadata' | 'eventHooks' | 'adminSettings' | 'writePublicAsset' | 'schema' | 'publicHtmlForPost' | 'secretSettings' | 'contentFields' | 'publicPostScript' | 'adminPage' | 'serverRoute' | 'network' | 'scheduler' | 'storageWrite' | 'privilegedSystem' | 'cspReady';
 /**
  * Loading strategy for `script` / `inlineScript` descriptors.
  *
@@ -971,6 +973,80 @@ interface PluginSettingsManifest {
      */
     version?: number;
 }
+/**
+ * Minimal tiptap node shape passed to a `contentFields` `tiptap` renderer.
+ * Mirrors the structural fields plugins typically read (`type`, `attrs`,
+ * `content`, `marks`, `text`) without coupling to a specific tiptap
+ * version. Plugins should treat unknown fields conservatively.
+ */
+interface TiptapRenderNode {
+    type: string;
+    attrs?: Record<string, unknown>;
+    content?: readonly TiptapRenderNode[];
+    marks?: readonly {
+        type: string;
+        attrs?: Record<string, unknown>;
+    }[];
+    text?: string;
+}
+/**
+ * Match object passed to a `contentFields` `markdown-url` renderer. The
+ * runtime walks the markdown body via `marked.lexer`, tests the trimmed
+ * single-line URL of each `paragraph` token against the registered
+ * pattern, and on match calls `render({ match, raw }, ctx)` so the
+ * plugin can extract capture groups (e.g. the YouTube video id) and
+ * return a ReactNode for that paragraph.
+ */
+interface MarkdownEmbedMatch {
+    match: RegExpMatchArray;
+    raw: string;
+}
+/**
+ * Renderer registered via `AmplessPlugin.contentFields`. Two variants:
+ *
+ * - `tiptap`: keyed by `nodeType` (e.g. `'amplessYoutube'`). The runtime
+ *   walks tiptap docs and, when the walker encounters a node whose
+ *   `type` matches `nodeType`, calls `render(node, ctx)` to produce a
+ *   ReactNode in place of the default switch-based HTML emission.
+ *
+ * - `markdown-url`: keyed by a fully-anchored `RegExp` (the pattern
+ *   should use `^...$`). The runtime tokenizes markdown via
+ *   `marked.lexer`, looks for `paragraph` tokens whose entire content
+ *   is a single URL (autolink / bare URL / `[text](url)` with matching
+ *   text), tests the URL against `pattern`, and on match calls
+ *   `render({ match, raw }, ctx)` for that paragraph.
+ *
+ * Each `nodeType` / `pattern.source` may be registered by at most one
+ * plugin — duplicate registration throws at `createPluginHead` time.
+ */
+type ContentFieldRenderer = {
+    kind: 'tiptap';
+    nodeType: string;
+    render(node: TiptapRenderNode, ctx: PluginPublicRenderContext): ReactNode;
+} | {
+    kind: 'markdown-url';
+    pattern: RegExp;
+    render(m: MarkdownEmbedMatch, ctx: PluginPublicRenderContext): ReactNode;
+};
+/**
+ * Descriptor returned by `AmplessPlugin.publicPostScript(post, ctx)`.
+ * The runtime aggregates descriptors across every post passed to
+ * `ampless.publicPostScriptsForPage(posts)` and emits each unique `id`
+ * once as `<script src={src} async defer />`.
+ *
+ * `id` must be a stable, plugin-defined identifier (e.g.
+ * `'amplessTweet:widgets'`). Multiple posts on the same page that all
+ * need the same script collapse into a single tag.
+ *
+ * `src` must be an absolute `http://` or `https://` URL — relative
+ * paths and other schemes are dropped with a warning.
+ */
+interface PublicPostScriptDescriptor {
+    id: string;
+    src: string;
+    async?: boolean;
+    defer?: boolean;
+}
 interface AmplessPlugin {
     name: string;
     /**
@@ -1152,6 +1228,40 @@ interface AmplessPlugin {
      * capability.
      */
     publicHtmlForPost?(post: Post, ctx: PluginPublicRenderContext): readonly PublicPostHtmlDescriptor[];
+    /**
+     * In-body content renderers (Phase 7 `contentFields` capability).
+     * Plugins register tiptap node renderers (keyed by `nodeType`) and/or
+     * markdown URL renderers (keyed by `RegExp`) here. The runtime walks
+     * post bodies during `ampless.renderBody(post)` and, on match, calls
+     * the renderer to obtain a `ReactNode` for that fragment in place of
+     * the default HTML output.
+     *
+     * Duplicate `nodeType` / `pattern.source` across plugins throws at
+     * `createPluginHead` construction time (eager config-time error). v1
+     * does not support multi-instance plugins registering the same
+     * renderer twice.
+     *
+     * Plugins implementing this should declare the `'contentFields'`
+     * capability.
+     */
+    contentFields?: readonly ContentFieldRenderer[];
+    /**
+     * Page-level script descriptors (Phase 7 `publicPostScript`
+     * capability). Themes call `ampless.publicPostScriptsForPage(posts)`
+     * after rendering post body / featured body; the runtime invokes
+     * `publicPostScript(post, ctx)` for each plugin × post pair, collects
+     * the descriptors, dedupes by `id`, and emits each unique entry as
+     * `<script src={src} async defer />`.
+     *
+     * Primary use case: x.com (Twitter) `widgets.js` to hydrate
+     * `<blockquote class="twitter-tweet">` blocks emitted by
+     * `contentFields`. YouTube embeds don't need this (the iframe loads
+     * its own script).
+     *
+     * Plugins implementing this should declare the `'publicPostScript'`
+     * capability.
+     */
+    publicPostScript?(post: Post, ctx: PluginPublicRenderContext): readonly PublicPostScriptDescriptor[];
     /**
      * Dynamic OG image renderer. The dispatcher route (e.g.
      * `app/og/[slug]/route.ts`) reads this and feeds the element into
@@ -1766,4 +1876,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 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 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 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 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 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

@@ -13,6 +13,8 @@
 
 設計の経緯と背景は [`docs/architecture/08-plugin-architecture.md`](https://github.com/heavymoons/ampless/blob/main/docs/architecture/08-plugin-architecture.md) に集約。本ページはその実装ハンドブック側です。
 
+> **ポジショニング**: ampless はエンジニア向けのカスタマイズベース CMS です — プラグインは**サイトエンジニアが `cms.config.ts` でインポート + 設定する npm dep** です。エンジニアは他の npm ライブラリと同様にインストール前に各 dep を審査します（Astro integration / Next.js plugin パターン）。このガイドで説明する trust framework（`trust_level`、capabilities、IAM スコープ付き Lambda）は v1 において**ファーストパーティプラグインの code organization**として実装されています — どの trust 階層の Lambda が各イベントフックを実行するか、各階層が保有する IAM 権限、そして狭い範囲のポイントでのみ runtime hard gate を適用する（最も重要: `settings.secret` は `trust_level: 'trusted'` を要求、シークレット読み取りに trusted Lambda の IAM 権限が必要なため）。ほとんどの capability 宣言は runtime の hard gate ではなく soft warning + admin ラベル + 将来の allow-list surface です。任意の未審査サードパーティ untrusted プラグインを自動的に安全に動かすための marketplace-grade automatic sandbox としては**設計されていません**。マーケットプレイス + ランタイムサンドボックスは v2.0+ の探索であり、v1 の保証ではありません。詳細な trust model は [`docs/architecture/08-plugin-architecture.md#trust-model-v1-scope`](https://github.com/heavymoons/ampless/blob/main/docs/architecture/08-plugin-architecture.md#trust-model-v1-scope) を参照してください。
+
 ---
 
 ## 0. テーマとプラグインの境界線
@@ -287,13 +289,15 @@ runtime がチェックする内容:
 
 ## 4. `trust_level` の選び方
 
+trust 階層は v1 において**ファーストパーティプラグインの code organization**として実装されています — イベントフックがどの IAM スコープ付き Lambda で実行されるか、その Lambda が保有する権限を決定します。これはエンジニアが審査した npm dep 向けの code organization surface であり、任意のサードパーティ未審査プラグインを自動的に安全に動かすための marketplace-grade automatic sandbox ではありません（上記の[ポジショニング注記](#ampless-プラグインの書き方)と[詳細な trust model](https://github.com/heavymoons/ampless/blob/main/docs/architecture/08-plugin-architecture.md#trust-model-v1-scope) を参照）。
+
 3 階層、選択基準は **イベントフック (hooks) が何を必要とするか** で決まります (sync サーフェスは IAM に触れない):
 
 | 階層 | IAM | 今日動くもの | 用途 |
 |---|---|---|---|
 | `untrusted` | なし (SQS consume のみ) | 同期サーフェス + イベントフック | head/body descriptor、webhook 配送、コンテンツ変換 |
 | `trusted` | 投稿読み出し、`public/plugins/<instanceId ?? name>/...` への書き込み | 同期サーフェス + イベントフック | RSS フィード、sitemap、計算済み JSON インデックス |
-| `privileged` | 予約 | 同期サーフェスのみ — イベントフックはサイレントフィルタ（警告ログあり） | 将来: SES、secret、private S3 |
+| `privileged` | 予約（v2.0+ 探索のみ） | 同期サーフェスのみ — イベントフックはサイレントフィルタ（警告ログあり） | 将来のマーケットプレイス探索: SES、secret、private S3 |
 
 > **`privileged` プラグイン作者へ：** `trust_level: 'privileged'` とイベント
 > `hooks` を宣言した場合、**現時点でフックは実行されません**。両 processor が
@@ -301,8 +305,10 @@ runtime がチェックする内容:
 > `console.warn` を出力するため、サイレントドロップは可視化されます。
 > 同期サーフェス（`publicHead`、`publicBodyEnd`、`metadata`、`publicBodyForPost`、
 > `publicHtmlForPost`）は `trust_level` に関わらず正常に動き、警告も出ません。
-> privileged Lambda が用意された際、`'privileged'` を宣言済みのプラグインは
-> 自動的に新しい tier を使えるようになります — コードの変更は不要です。
+> privileged Lambda プロビジョニングは v2.0+ の探索項目です — ampless が
+> プラグインマーケットプレイスを構築する場合、すでに `'privileged'` を宣言した
+> プラグインは自動的に新しい tier を使えるようになります。
+> v1 ファーストパーティプラグインは trusted Lambda の現行 IAM スコープに収まる用途で `trust_level: 'trusted'` を使ってください。すなわち Post / KvStore / PluginSecret / PostTag の読み取り、`public/plugins/*` への S3 書き込み、外向き HTTP (AWS IAM 認証を必要としないもの) です。このスコープ外の要件 — SES、private S3 プレフィックス、自前の IAM プリンシパルを必要とする AWS API 呼び出し — は v2.0+ privileged Lambda 探索の対象で、v1 `trusted` には収まりません。
 
 決め方の目安:
 
@@ -540,7 +546,7 @@ export default function readingTimePlugin() {
 ```tsx
 {postBody}            {/* publicBodyForPost — JSON-LD */}
 {html.beforeContent}  {/* publicHtmlForPost — beforeContent スロット */}
-<div className="prose" dangerouslySetInnerHTML={{ __html: renderBody(post) }} />
+<div className="prose">{await ampless.renderBody(post)}</div>
 {html.afterContent}   {/* publicHtmlForPost — afterContent スロット */}
 ```
 
@@ -678,6 +684,166 @@ npm 公開のスタンドアロンプラグインの場合は、`package.json#am
 
 ---
 
+## 6b. 投稿本文の差し替え: `contentFields` (Phase 7)
+
+`contentFields` capability は、投稿本文の一部（tiptap ノード、または markdown の単独行 URL）を、プラグインが管理する React サブツリーで差し替える機能。`@ampless/plugin-youtube` / `@ampless/plugin-x-embed` が `https://youtu.be/...` URL を iframe プレーヤーに、`https://x.com/<handle>/status/...` URL を tweet blockquote に展開するために使う。
+
+### 形
+
+```ts
+import { definePlugin, type ContentFieldRenderer } from 'ampless'
+
+definePlugin({
+  // ...
+  capabilities: ['contentFields'],
+  contentFields: [
+    {
+      kind: 'tiptap',
+      nodeType: 'amplessYoutube',
+      render: (node, ctx) => <YouTubeEmbed videoId={String(node.attrs?.videoId)} />,
+    },
+    {
+      kind: 'markdown-url',
+      pattern: /^https:\/\/youtu\.be\/([\w-]{11})$/,
+      render: ({ match }, ctx) => <YouTubeEmbed videoId={match[1]!} />,
+    },
+  ],
+})
+```
+
+各 renderer は `ampless.renderBody(post)` 内で本文を歩く runtime から server-side で呼び出される。戻り値は `ReactNode`。`PluginPublicRenderContext` (`ctx`) は `publicHead` / `publicBodyEnd` と同じものなので、`ctx.setting<T>(key)` も同じように使える。
+
+### 2 種類の kind
+
+- **`tiptap`** — `nodeType` (例: `'amplessYoutube'`) でキー付け。runtime の tiptap walker が `type` 一致のノードを見つけたら renderer を呼ぶ。デフォルトの switch-case レンダリングはバイパスされ、プラグインがサブツリー全体を所有する。
+- **`markdown-url`** — anchored な `RegExp` (`^...$`) でキー付け。runtime は `marked.lexer` で markdown をトークン化し、内容全体が単独 URL の paragraph トークン (autolink / bare URL / `[text](url)`) のみについて pattern を試す。最初にマッチしたものが勝ち。capture group は `match[1]`, `match[2]`, ... でアクセス可能。
+
+### 命名と一意性
+
+- first-party プラグインは `ampless...` の camelCase プレフィックス（`amplessYoutube`, `amplessTweet` 等）を使い、コミュニティ製の `nodeType` と衝突しないようにしている。
+- runtime は同じ `nodeType` / `pattern.source` の重複登録を起動時に throw で拒否する。先勝ち。v1 は multi-instance 非対応。
+
+### markdown URL pattern のルール
+
+- **必ず `^...$` で anchor する**。anchor なしだと段落内の URL が誤マッチし、周辺テキストが壊れる。
+- runtime はマッチ前に前後の whitespace を trim するので、pattern 側で `\s*` を書く必要はない。
+- 段落の唯一のトークンが `[caption](url)` の markdown link なら受理する。`[caption with link](url)` のように前後にテキストが混在するケースは対象外（正しい挙動: prose は本文に残すべきで、video embed にすべきではない）。
+
+---
+
+## 6c. ページレベルスクリプト: `publicPostScript` (Phase 7)
+
+`publicPostScript` capability は、ページ上の投稿が必要とする `<script>` タグをプラグインから出力するためのもの。runtime は安定 `id` で dedupe するので、同一ページ内の複数 embed は 1 つの script タグに集約される。`@ampless/plugin-x-embed` がページに tweet embed がある場合のみ `https://platform.twitter.com/widgets.js` を 1 度だけ注入するのに使われている。
+
+### 形
+
+```ts
+definePlugin({
+  capabilities: ['contentFields', 'publicPostScript'],
+  publicPostScript(post, ctx) {
+    if (!hasTweetIn(post)) return []
+    return [
+      {
+        id: 'amplessTweet:widgets',
+        src: 'https://platform.twitter.com/widgets.js',
+        async: true,
+      },
+    ]
+  },
+})
+```
+
+### テーマからの呼び出し
+
+テーマは投稿本文の出力後に `{await ampless.publicPostScriptsForPage(posts)}` を呼ぶ。first-party テーマは post 詳細ページ / home ページ (featured 表示時) で自動的に呼び出す:
+
+```tsx
+<div>{await ampless.renderBody(post)}</div>
+{await ampless.publicPostScriptsForPage([post])}
+```
+
+runtime は:
+
+1. プラグイン × post 組ごとに `publicPostScript(post, ctx)` を呼ぶ。
+2. `id` が空 / 非 string、`src` が http(s) でない、descriptor がオブジェクトでない、等を drop。
+3. `id` で dedupe（先勝ち）。
+4. `<Fragment>` で `<script src={src} async defer />` を出力。
+
+### CSP の扱い
+
+runtime は `src` のホスト allowlist を強制しない。CSP はサイト側エンジニアの責任（`next.config.ts` / middleware で `script-src` に script ホスト（例: `platform.twitter.com`）を追加）。各プラグインの README に書いてある。
+
+---
+
+## 6d. Admin エディタ拡張の配線 (Phase 7)
+
+admin エディタに tiptap Node 拡張を提供するプラグインは、別途 `./editor` subpath の client-side エントリを出荷する。テンプレート側で `_editor-bootstrap.tsx` から配線する:
+
+```tsx
+// templates/_shared/app/(admin)/admin/_editor-bootstrap.tsx
+'use client'
+import { installAdminEditorExtensions } from '@ampless/admin/editor'
+import { youtubeEditor } from '@ampless/plugin-youtube/editor'
+import { tweetEditor } from '@ampless/plugin-x-embed/editor'
+
+export function EditorBootstrap({ children }: { children: React.ReactNode }) {
+  installAdminEditorExtensions([
+    youtubeEditor.extension,
+    tweetEditor.extension,
+  ])
+  return <>{children}</>
+}
+```
+
+その上で layout に渡す:
+
+```tsx
+// templates/_shared/app/(admin)/admin/layout.tsx
+import { createAdminLayout } from '@ampless/admin/pages'
+import { EditorBootstrap } from './_editor-bootstrap'
+export default createAdminLayout(admin, { editorBootstrap: EditorBootstrap })
+```
+
+`installAdminEditorExtensions` は idempotent で、render 時に client component 内で呼ばれる。admin の `<TiptapEditor>` は毎回 render 時に登録済みリストを built-in extensions の末尾に spread する。
+
+### エディタプレビューのパイプライン
+
+admin の edit / new post フォームは preview ペインを `<iframe sandbox="allow-scripts">` で表示する。`srcDoc` はテンプレート側 server action が返す HTML:
+
+```tsx
+// templates/_shared/app/(admin)/admin/_actions/render-preview.tsx
+'use server'
+import { renderToStaticMarkup } from 'react-dom/server'
+import type { Post } from 'ampless'
+import { admin } from '@/lib/admin'
+
+export async function renderPreviewHtml(draft: Post): Promise<string> {
+  const ampless = await admin.getAmpless()
+  const node = (
+    <>
+      {await ampless.renderBody(draft)}
+      {await ampless.publicPostScriptsForPage([draft])}
+    </>
+  )
+  return renderToStaticMarkup(node)
+}
+```
+
+page factory は `renderPreviewAction` オプションでこの action を thread する:
+
+```tsx
+// templates/_shared/app/(admin)/admin/posts/[postId]/page.tsx
+import { admin } from '@/lib/admin'
+import { createEditPostPage } from '@ampless/admin/pages'
+import { renderPreviewHtml } from '../../_actions/render-preview'
+
+export default createEditPostPage(admin, { renderPreviewAction: renderPreviewHtml })
+```
+
+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 を緩めるのは取らない。
+
+---
+
 ## 7. 非同期イベントフック
 
 `hooks` は SQS から到着したイベントを trust_level に対応する processor Lambda が受けて実行します。
@@ -862,12 +1028,18 @@ Secret settings を使うと、trusted プラグインが認証情報 (Webhook
 - 公開 render surface (`publicHead` など) からは読めない。
 - **field manifest 検証の範囲**: admin クライアントは UX フィードバック目的で `pattern` / `maxLength` / `required` を検証するが、Lambda 側は **汎用の 10,000 文字ハードキャップと安全文字サニタイザのみ**を強制する。admin/editor が AppSync mutation を直接呼ぶと field 単位の制約は迂回できる。設計上意図したもので、admin/editor は secret 設定を許可された信頼されたオペレータと位置づけている。manifest チェックは UX ガイダンスであり、セキュリティ境界ではない。
 
-### 要件
+### 要件と `definePlugin()` の挙動
+
+`settings.secret` は `definePlugin()` 時に 4 つの observable な挙動を持ちます（これは v1 のファーストパーティ organization のシークレットアクセス hard gate; [plugin.ts:1004-1019](https://github.com/heavymoons/ampless/blob/main/packages/ampless/src/plugin.ts#L1004-L1019) 参照）:
 
-`settings.secret` には 3 つの要件があります:
+1. **`settings.secret` 非空 + `trust_level !== 'trusted'`** → `definePlugin()` が **throw**。untrusted と privileged Lambda は `PluginSecret` テーブルへの IAM read アクセスを持たない; trusted Lambda の IAM 権限が必要。
+2. **`settings.secret` 非空 + `capabilities` 宣言済み + `capabilities` に `'secretSettings'` が含まれない** → **soft 不一致 warning**。`'schema'` / `'publicHtmlForPost'` の既存 capability-mismatch パターンと同じ。
+3. **`settings.secret` 非空 + `capabilities` 未定義**（`capabilities` 配列を持たない legacy プラグイン）→ **warning なし**。`capabilities` が `undefined` のとき不一致チェックをスキップ、後方互換のため。
+4. **`capabilities: ['secretSettings']` 宣言だけで `settings.secret` フィールドなし** → **no-op**。warning も throw もなし。
 
-1. `trust_level: 'trusted'` — untrusted Lambda には PluginSecret table への DDB read 権限がない。他の trust level で宣言すると `definePlugin()` 時に throw する。
-2. `'secretSettings'` を `capabilities` に含める — admin UI や将来の allow-list から capability を参照できるようにするため必須。省略すると console.warn（`'schema'` vs `publicBodyForPost` の不整合パターンと同じ）。
+`settings.secret` を使うには以下も必要です:
+1. `trust_level: 'trusted'`（上記 #1 の要件; それ以外は `definePlugin()` が throw）。
+2. `capabilities` に `'secretSettings'` を含める（`capabilities` が定義されているとき省略すると console.warn）。
 3. **鍵の初回セットアップ** — プロジェクトルートで実行:
    ```sh
    npx create-ampless setup-encryption-key
@@ -1234,7 +1406,7 @@ it('admin が空文字保存した場合は空配列', () => {
 - [`packages/plugin-plausible`](https://github.com/heavymoons/ampless/tree/main/packages/plugin-plausible) — `data-*` attrs 付きの単一 `<script>` descriptor、`required` な URL field（self-hosted Plausible 上書き対応）
 - [`packages/plugin-rss`](https://github.com/heavymoons/ampless/tree/main/packages/plugin-rss) — trusted、非同期 hooks + `writePublicAsset`
 - [`packages/plugin-seo`](https://github.com/heavymoons/ampless/tree/main/packages/plugin-seo) — `metadata()` + `siteMetadata()`
-- [`packages/plugin-webhook`](https://github.com/heavymoons/ampless/tree/main/packages/plugin-webhook) — untrusted hook + 外向き HTTP
+- [`packages/plugin-webhook`](https://github.com/heavymoons/ampless/tree/main/packages/plugin-webhook) — trusted hook + 外向き HTTP + `secretSettings` (admin 管理の signing secret、Phase 6a)
 - [`packages/plugin-og-image`](https://github.com/heavymoons/ampless/tree/main/packages/plugin-og-image) — `ogImage` ルートレンダラ
 - [`packages/plugin-schema-jsonld`](https://github.com/heavymoons/ampless/tree/main/packages/plugin-schema-jsonld) — `publicBodyForPost` + `schema` capability、投稿単位 Article JSON-LD。（Phase 4）
 

package/docs/plugin-author-guide.md

@@ -19,6 +19,8 @@ per-post body injection, the async event hooks, and admin-managed
 The design rationale is in [`docs/architecture/08-plugin-architecture.md`](https://github.com/heavymoons/ampless/blob/main/docs/architecture/08-plugin-architecture.md);
 this page is the hands-on companion.
 
+> **Positioning**: ampless is a customization-based CMS for engineers — plugins are **npm dependencies that the site engineer imports + configures in `cms.config.ts`**. The engineer audits each dep before installing, the way they would for any other npm library (Astro integration / Next.js plugin pattern). The trust framework described in this guide (`trust_level`, capabilities, IAM-scoped Lambdas) is implemented in v1 as **first-party plugin organization** — it decides which trust tier's Lambda runs each event hook, which IAM permissions each tier holds, and applies hard runtime gates only at narrowly-scoped points (most notably: `settings.secret` requires `trust_level: 'trusted'` because secret read needs the trusted Lambda's IAM permission). Most capability declarations are soft warnings + admin labels + future allow-list surfaces, not hard runtime gates. It is **not** designed as a marketplace-grade automatic sandbox that safely runs arbitrary untrusted third-party plugins. Marketplace + runtime sandbox is a v2.0+ exploration, not a v1 guarantee. See [`docs/architecture/08-plugin-architecture.md#trust-model-v1-scope`](https://github.com/heavymoons/ampless/blob/main/docs/architecture/08-plugin-architecture.md#trust-model-v1-scope) for the full trust model.
+
 ---
 
 ## 0. Theme vs Plugin Boundary
@@ -358,6 +360,8 @@ not a runtime block.
 
 ## 4. Picking a `trust_level`
 
+The trust tiers are implemented in v1 as **first-party plugin organization** — they decide which IAM-scoped Lambda runs your event hooks and which permissions that Lambda holds. This is a code organization surface for engineer-audited npm deps, not a marketplace-grade automatic sandbox for arbitrary third-party untrusted plugins (see the [Positioning note](#writing-an-ampless-plugin) above and the [full trust model](https://github.com/heavymoons/ampless/blob/main/docs/architecture/08-plugin-architecture.md#trust-model-v1-scope)).
+
 Three tiers, picked by what the plugin needs to do **inside
 event hooks** (the sync surfaces — metadata, head, body — don't
 touch IAM):
@@ -366,7 +370,7 @@ touch IAM):
 |---|---|---|---|
 | `untrusted` | none (SQS consume only) | sync surfaces + event hooks | head/body descriptors, webhook delivery, content transforms |
 | `trusted` | read posts, write `public/plugins/<instanceId ?? name>/...` | sync surfaces + event hooks | RSS feed, sitemap, computed JSON indexes |
-| `privileged` | reserved | sync surfaces only — event hooks are silently filtered out (warning logged) | future: SES, secrets, private S3 |
+| `privileged` | reserved (v2.0+ exploration only) | sync surfaces only — event hooks are silently filtered out (warning logged) | future marketplace exploration: SES, secrets, private S3 |
 
 > **Warning for `privileged` plugin authors:** If you declare
 > `trust_level: 'privileged'` with event `hooks` today, **your hooks
@@ -375,9 +379,10 @@ touch IAM):
 > the drop is visible. Sync render surfaces (`publicHead`,
 > `publicBodyEnd`, `metadata`, `publicBodyForPost`, `publicHtmlForPost`)
 > work normally regardless of `trust_level` and emit no warning.
-> When the privileged Lambda provisioning PR lands, plugins that
-> already declared `'privileged'` will automatically pick up the new
-> tier — nothing needs to change in your code.
+> `privileged` Lambda provisioning is a v2.0+ exploration item — if
+> AmpLess later builds a plugin marketplace, that PR will automatically
+> pick up plugins that already declared `'privileged'`.
+> v1 first-party plugins should use `trust_level: 'trusted'` for capabilities that fit within the trusted Lambda's existing IAM scope: Post / KvStore / PluginSecret / PostTag read, `public/plugins/*` S3 write, and outbound HTTP (no AWS-IAM-authenticated calls). Requirements that fall outside that scope — SES, private S3 prefixes, calling AWS APIs that need an IAM principal of their own — are v2.0+ privileged-Lambda exploration material and don't fit into v1 `trusted`.
 
 Rule of thumb:
 
@@ -673,7 +678,7 @@ the slots:
 ```tsx
 {postBody}            {/* publicBodyForPost — JSON-LD */}
 {html.beforeContent}  {/* publicHtmlForPost — beforeContent slot */}
-<div className="prose" dangerouslySetInnerHTML={{ __html: renderBody(post) }} />
+<div className="prose">{await ampless.renderBody(post)}</div>
 {html.afterContent}   {/* publicHtmlForPost — afterContent slot */}
 ```
 
@@ -889,6 +894,218 @@ manifest and the factory return value:
 
 ---
 
+## 6b. In-body content renderers: `contentFields` (Phase 7)
+
+The `contentFields` capability lets a plugin replace specific fragments
+of a post body — tiptap nodes or single-line markdown URLs — with a
+React subtree it controls. Used by the first-party `@ampless/plugin-youtube`
+and `@ampless/plugin-x-embed` packages to expand `https://youtu.be/...`
+URLs into iframe players and `https://x.com/<handle>/status/...` URLs
+into tweet blockquotes.
+
+### Shape
+
+```ts
+import { definePlugin, type ContentFieldRenderer } from 'ampless'
+
+definePlugin({
+  // ...
+  capabilities: ['contentFields'],
+  contentFields: [
+    {
+      kind: 'tiptap',
+      nodeType: 'amplessYoutube',
+      render: (node, ctx) => <YouTubeEmbed videoId={String(node.attrs?.videoId)} />,
+    },
+    {
+      kind: 'markdown-url',
+      pattern: /^https:\/\/youtu\.be\/([\w-]{11})$/,
+      render: ({ match }, ctx) => <YouTubeEmbed videoId={match[1]!} />,
+    },
+  ],
+})
+```
+
+Each renderer is called server-side by the runtime when it walks a post
+body during `ampless.renderBody(post)`. The return value must be a
+`ReactNode`. The plugin's `PluginPublicRenderContext` (`ctx`) is the
+same context handed to `publicHead` / `publicBodyEnd`, so `ctx.setting<T>(key)`
+works exactly the same way.
+
+### The two kinds
+
+- **`tiptap`** — keyed by `nodeType` (a string, e.g. `'amplessYoutube'`).
+  The runtime's tiptap walker calls the renderer whenever it encounters
+  a node whose `type` matches `nodeType`. Default switch-case rendering
+  is bypassed; the plugin owns the subtree.
+- **`markdown-url`** — keyed by an anchored `RegExp` (`^...$`). The
+  runtime tokenizes markdown with `marked.lexer` and, for any
+  `paragraph` token whose entire content is a single URL (autolink,
+  bare URL, or `[text](url)` markdown link), tests the URL against
+  each registered pattern. The first match wins; capture groups are
+  exposed via `match[1]`, `match[2]`, etc.
+
+### Naming and uniqueness
+
+- First-party plugins use the `ampless...` camelCase prefix
+  (`amplessYoutube`, `amplessTweet`) so the namespace stays clear of
+  community-contributed `nodeType`s.
+- The runtime rejects duplicate `nodeType` / `pattern.source` at
+  startup with a thrown error. The first plugin to register a given key
+  wins; the second one fails fast. Multi-instance v1 is not supported.
+
+### Markdown URL pattern rules
+
+- **Always anchor with `^...$`** so the pattern only matches paragraphs
+  whose entire content is a single URL. A pattern without anchors would
+  match URLs embedded mid-paragraph and break the surrounding text.
+- The runtime trims leading/trailing whitespace before matching, so
+  patterns don't need to account for `\s*` around the URL.
+- Inline `[caption](url)` markdown links are accepted when the link is
+  the paragraph's only token. `[caption with link](url)` mixed with
+  surrounding text is NOT matched (correct behaviour: the prose
+  belongs in the post, not a video embed).
+
+---
+
+## 6c. Page-level scripts: `publicPostScript` (Phase 7)
+
+The `publicPostScript` capability lets a plugin emit a `<script>` tag
+that any post on the page needs. The runtime dedupes by stable `id`
+so multiple embeds in one or several posts collapse to one script tag.
+Used by `@ampless/plugin-x-embed` to inject
+`https://platform.twitter.com/widgets.js` once per page that has any
+tweet embed.
+
+### Shape
+
+```ts
+definePlugin({
+  capabilities: ['contentFields', 'publicPostScript'],
+  publicPostScript(post, ctx) {
+    if (!hasTweetIn(post)) return []
+    return [
+      {
+        id: 'amplessTweet:widgets',
+        src: 'https://platform.twitter.com/widgets.js',
+        async: true,
+      },
+    ]
+  },
+})
+```
+
+### Theme integration
+
+Themes call `{await ampless.publicPostScriptsForPage(posts)}` after
+rendering each post body. First-party themes do this automatically in
+their post detail page and home page (when a featured post is shown):
+
+```tsx
+<div>{await ampless.renderBody(post)}</div>
+{await ampless.publicPostScriptsForPage([post])}
+```
+
+The runtime:
+
+1. Calls `publicPostScript(post, ctx)` for each plugin × post pair.
+2. Drops descriptors with empty/non-string `id`, with `src` that fails
+   the http(s) allowlist, or that aren't objects.
+3. Dedupes by `id` (first arrival wins).
+4. Emits a `<Fragment>` of `<script src={src} async defer />` elements.
+
+### CSP considerations
+
+The runtime does **not** enforce a host allowlist on `src`. CSP is the
+site engineer's responsibility — add the script host (e.g.
+`platform.twitter.com`) to `script-src` in `next.config.ts` /
+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`:
+
+```tsx
+// templates/_shared/app/(admin)/admin/_editor-bootstrap.tsx
+'use client'
+import { installAdminEditorExtensions } from '@ampless/admin/editor'
+import { youtubeEditor } from '@ampless/plugin-youtube/editor'
+import { tweetEditor } from '@ampless/plugin-x-embed/editor'
+
+export function EditorBootstrap({ children }: { children: React.ReactNode }) {
+  installAdminEditorExtensions([
+    youtubeEditor.extension,
+    tweetEditor.extension,
+  ])
+  return <>{children}</>
+}
+```
+
+Then thread it into the layout:
+
+```tsx
+// templates/_shared/app/(admin)/admin/layout.tsx
+import { createAdminLayout } from '@ampless/admin/pages'
+import { EditorBootstrap } from './_editor-bootstrap'
+export default createAdminLayout(admin, { editorBootstrap: EditorBootstrap })
+```
+
+`installAdminEditorExtensions` is idempotent and runs at render time
+inside a client component. The admin's `<TiptapEditor>` spreads the
+registered list onto its built-in extensions on every render.
+
+### 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
+by the template's server action:
+
+```tsx
+// templates/_shared/app/(admin)/admin/_actions/render-preview.tsx
+'use server'
+import { renderToStaticMarkup } from 'react-dom/server'
+import type { Post } from 'ampless'
+import { admin } from '@/lib/admin'
+
+export async function renderPreviewHtml(draft: Post): Promise<string> {
+  const ampless = await admin.getAmpless()
+  const node = (
+    <>
+      {await ampless.renderBody(draft)}
+      {await ampless.publicPostScriptsForPage([draft])}
+    </>
+  )
+  return renderToStaticMarkup(node)
+}
+```
+
+Page factories thread the action down via the `renderPreviewAction`
+option:
+
+```tsx
+// templates/_shared/app/(admin)/admin/posts/[postId]/page.tsx
+import { admin } from '@/lib/admin'
+import { createEditPostPage } from '@ampless/admin/pages'
+import { renderPreviewHtml } from '../../_actions/render-preview'
+
+export default createEditPostPage(admin, { renderPreviewAction: renderPreviewHtml })
+```
+
+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.
+
+---
+
 ## 7. Async event hooks
 
 `hooks` runs inside the trust_level-matched processor Lambda when an
@@ -1150,16 +1367,18 @@ etc. — but completely wrong for a webhook signing secret.
   (`publicHead`, `publicBodyEnd`, `publicBodyForPost`,
   `publicHtmlForPost`) — those surfaces only see `ctx.setting()`.
 
-### Requirements
+### Requirements and `definePlugin()` behaviour
+
+`settings.secret` has four observable behaviours at `definePlugin()` time (this is the v1 first-party organization hard gate for secret access; see [plugin.ts:1004-1019](https://github.com/heavymoons/ampless/blob/main/packages/ampless/src/plugin.ts#L1004-L1019)):
 
-`settings.secret` requires:
+1. **`settings.secret` non-empty + `trust_level !== 'trusted'`** → `definePlugin()` **throws**. Untrusted and privileged Lambdas have no IAM read access to the `PluginSecret` table; the trusted Lambda's IAM permission is required.
+2. **`settings.secret` non-empty + `capabilities` declared + `'secretSettings'` missing from `capabilities`** → **soft mismatch warning**. Matches the existing capability-mismatch pattern for `'schema'` / `'publicHtmlForPost'`.
+3. **`settings.secret` non-empty + `capabilities` undefined** (legacy plugin without a `capabilities` array) → **no warning**. The mismatch check is skipped when `capabilities` is `undefined`, for backward compatibility.
+4. **`capabilities: ['secretSettings']` declared with no `settings.secret` field** → **no-op**. Neither warning nor throw.
 
-1. `trust_level: 'trusted'` — untrusted Lambdas have no DDB read
-   access to the PluginSecret table. `definePlugin()` throws if you
-   declare `settings.secret` with any other trust level.
-2. `'secretSettings'` in `capabilities` — required so admin UI and
-   future allow-lists can gate the capability. Omitting it produces
-   a console warning (same pattern as `'schema'` vs `publicBodyForPost`).
+To use `settings.secret`, you also need:
+1. `trust_level: 'trusted'` (requirement #1 above; `definePlugin()` throws otherwise).
+2. `'secretSettings'` in `capabilities` (omitting it when `capabilities` is defined produces a console warning).
 3. **One-time key setup** — run from your project root:
    ```sh
    npx create-ampless setup-encryption-key
@@ -1676,7 +1895,7 @@ Worked examples to crib from:
 - [`packages/plugin-plausible`](https://github.com/heavymoons/ampless/tree/main/packages/plugin-plausible) — single `<script>` descriptor with `data-*` attrs and a required URL field (self-hosted Plausible override).
 - [`packages/plugin-rss`](https://github.com/heavymoons/ampless/tree/main/packages/plugin-rss) — trusted, async event hooks + `writePublicAsset`.
 - [`packages/plugin-seo`](https://github.com/heavymoons/ampless/tree/main/packages/plugin-seo) — `metadata()` + `siteMetadata()`.
-- [`packages/plugin-webhook`](https://github.com/heavymoons/ampless/tree/main/packages/plugin-webhook) — untrusted hook with outbound HTTP.
+- [`packages/plugin-webhook`](https://github.com/heavymoons/ampless/tree/main/packages/plugin-webhook) — trusted hook with outbound HTTP + `secretSettings` (admin-managed signing secret, Phase 6a).
 - [`packages/plugin-og-image`](https://github.com/heavymoons/ampless/tree/main/packages/plugin-og-image) — `ogImage` route renderer.
 - [`packages/plugin-schema-jsonld`](https://github.com/heavymoons/ampless/tree/main/packages/plugin-schema-jsonld) — `publicBodyForPost` + `schema` capability; per-post Article JSON-LD. (Phase 4)
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ampless",
-  "version": "1.0.0-alpha.40",
+  "version": "1.0.0-alpha.42",
   "description": "Serverless CMS for AWS Amplify",
   "license": "MIT",
   "type": "module",
@@ -32,6 +32,17 @@
   "dependencies": {
     "@jsquash/webp": "^1.5.0"
   },
+  "peerDependencies": {
+    "@types/react": "^19"
+  },
+  "peerDependenciesMeta": {
+    "@types/react": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@types/react": "^19.2.15"
+  },
   "keywords": [
     "cms",
     "aws",