ampless 1.0.0-alpha.41 → 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

@@ -546,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 スロット */}
 ```
 
@@ -684,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 が受けて実行します。

package/docs/plugin-author-guide.md

@@ -678,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 */}
 ```
 
@@ -894,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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ampless",
-  "version": "1.0.0-alpha.41",
+  "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",