ampless 1.0.0-alpha.46 → 1.0.0-alpha.47

package/dist/index.d.ts

@@ -1014,6 +1014,30 @@ interface TiptapRenderNode {
  */
 type TiptapNodeToMarkdown = (node: TiptapRenderNode) => string | null;
 type TiptapNodeMarkdownAdapters = Readonly<Record<string, TiptapNodeToMarkdown>>;
+/**
+ * Adapter that converts a single tiptap node to its canonical HTML placeholder
+ * div form. Plugins that ship an embed node (e.g. amplessYoutube →
+ * `<div data-ampless-youtube data-video-id="...">…</div>`) export a map from
+ * nodeType to adapter from their `./editor` module (named export
+ * `tiptapNodeToHtml`); `update-ampless` wires the map into
+ * `installAdminTiptapNodeHtml` so the admin's `tiptap → html` format switch
+ * can losslessly serialise the embed to the canonical placeholder div form.
+ *
+ * The canonical div is what tiptap's `Node.renderHTML` emits and what the
+ * `Node.parseHTML` `tag: 'div[data-ampless-*]'` rule restores from. It is an
+ * admin format-switch interchange form; public rendering expands embeds from
+ * the `tiptap` / `markdown` walkers, while `format: 'html'` preserves the div
+ * literally.
+ *
+ * The `markdown → html` direction is a 2-hop via `generateJSON(...)` so
+ * plugins only need to export the `tiptap → html` adapter; the markdown side
+ * reuses it via tiptap's parseHTML rules (no duplicate logic).
+ *
+ * Return `null` (or simply omit the nodeType from the map) to fall through to
+ * the runtime's default HTML switch.
+ */
+type TiptapNodeToHtml = (node: TiptapRenderNode) => string | null;
+type TiptapNodeHtmlAdapters = Readonly<Record<string, TiptapNodeToHtml>>;
 /**
  * Match object passed to a `contentFields` `markdown-url` renderer. The
  * runtime walks the markdown body via `marked.lexer`, tests the trimmed
@@ -1901,4 +1925,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 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 };
+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 TiptapNodeHtmlAdapters, type TiptapNodeMarkdownAdapters, type TiptapNodeToHtml, 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

@@ -848,6 +848,114 @@ export default createAdminLayout(admin, { editorBootstrap: EditorBootstrap })
 
 `installAdminEditorExtensions` は idempotent で、render 時に client component 内で呼ばれる。admin の `<TiptapEditor>` は毎回 render 時に登録済みリストを built-in extensions の末尾に spread する。
 
+`update-ampless` が生成する `_editor-bootstrap.tsx` は extensions、markdown アダプター、html アダプターの3つの install 呼び出しを含む:
+
+```tsx
+// app/(admin)/admin/_editor-bootstrap.tsx  (AUTO-GENERATED — 編集不可)
+'use client'
+// AUTO-GENERATED by `npm run update-ampless`. Do not edit ...
+import { installAdminEditorExtensions, installAdminTiptapNodeMarkdown, installAdminTiptapNodeHtml } from '@ampless/admin/editor'
+import * as __ampless_plugin_x_embed_editor from '@ampless/plugin-x-embed/editor'
+import * as __ampless_plugin_youtube_editor from '@ampless/plugin-youtube/editor'
+
+export function EditorBootstrap({ children }: { children: React.ReactNode }) {
+  installAdminEditorExtensions([
+    __ampless_plugin_x_embed_editor.editorExtension,
+    __ampless_plugin_youtube_editor.editorExtension,
+  ])
+  installAdminTiptapNodeMarkdown([
+    __ampless_plugin_x_embed_editor.tiptapNodeToMarkdown ?? {},
+    __ampless_plugin_youtube_editor.tiptapNodeToMarkdown ?? {},
+  ])
+  installAdminTiptapNodeHtml([
+    __ampless_plugin_x_embed_editor.tiptapNodeToHtml ?? {},
+    __ampless_plugin_youtube_editor.tiptapNodeToHtml ?? {},
+  ])
+  return <>{children}</>
+}
+```
+
+### フォーマット切り替えの可逆アダプター（`tiptapNodeToMarkdown` + `tiptapNodeToHtml`）
+
+operator が admin UI でポストのフォーマットを切り替える場合（例: `tiptap → markdown`、`tiptap → html`）、admin はボディコンテンツを変換する必要がある。通常の prose node は tiptap の built-in レンダラーで処理されるが、**atom node**（`amplessYoutube` のような embed ブロック）は子要素を持たず、children が空のまま fallthrough し、embed が無音で消えてしまう。
+
+2 つのアダプターで両方向を修正する:
+
+| アダプター            | 方向                              | 出力 |
+| --------------------- | --------------------------------- | ---- |
+| `tiptapNodeToMarkdown`| `tiptap → markdown`               | bare URL 行（例: `https://youtu.be/<id>`） |
+| `tiptapNodeToHtml`    | `tiptap → html`、`markdown → html`| 正規プレースホルダー div |
+
+フォーマット切替で扱う 3 種類の正規 body 表現:
+
+| フォーマット | 正規形 |
+| ------------ | ------ |
+| tiptap       | `{ type: 'amplessYoutube', attrs: { videoId, start } }` Node |
+| markdown     | bare `https://youtu.be/<id>` URL 行 |
+| html         | `<div data-ampless-youtube data-video-id="<id>" …>…</div>` |
+
+プレースホルダー div は **admin format-switch 相互運用専用**の正規 HTML 形式: `Node.renderHTML` が emit し、`Node.parseHTML` の `tag: 'div[data-ampless-*]'` rule が復元することで、admin での `tiptap ↔ markdown ↔ html` 切替が embed を保ったまま round-trip できる。
+
+**`format: 'html'` の公開描画ではプレースホルダー展開を行わない。** 公開描画はフォーマット別に分岐: tiptap 投稿は React walker が `contentFields.tiptap` registry を参照（= `amplessYoutube` Node を実際の iframe に変換）、markdown 投稿は markdown walker が `contentFields.markdownUrl` を参照（= bare URL paragraph を実際の iframe に変換）、html 投稿は `htmlPassthroughBlock` で raw HTML をそのまま出力する。**プレースホルダー div を含む html-format 投稿は公開ページでリテラル div として表示される。** `publicHtmlForPost` は `beforeContent` / `afterContent` slot のみ提供する capability であり、body を変換しない。
+
+embed を公開ページで実際に描画させたい場合は、投稿を `tiptap` または `markdown` 形式で保存する（= format-switch round-trip で embed Node / bare URL line に戻り、対応する公開 walker が iframe を emit する）。`html` 形式は **engineer が完全制御で書く raw HTML** として扱われる前提で、プレースホルダーは format-switch round-trip の artefact であって描画可能な embed reference ではない。`data-ampless-*` プレースホルダーを public html walker で iframe に展開する将来 capability は本セクション末尾の follow-up note を参照。
+
+#### アダプターの契約
+
+両アダプターは同じシグネチャを持つ:
+
+```ts
+(node: TiptapRenderNode) => string | null
+```
+
+**文字列**（空文字 `''` も含む）を返すと、その出力を使う。**`null`** を返すとデフォルトの switch へ fallthrough する（対応しない node や video id が欠損している場合などに使う）。
+
+```ts
+// packages/plugin-youtube/src/editor.tsx
+import type { TiptapNodeMarkdownAdapters, TiptapNodeHtmlAdapters } from 'ampless'
+
+export const tiptapNodeToMarkdown: TiptapNodeMarkdownAdapters = {
+  amplessYoutube: (node) => {
+    const videoId = String(node.attrs?.videoId ?? '').trim()
+    if (!videoId) return null   // fallthrough
+    return `https://youtu.be/${videoId}`
+  },
+}
+
+export const tiptapNodeToHtml: TiptapNodeHtmlAdapters = {
+  amplessYoutube: (node) => {
+    const videoId = String(node.attrs?.videoId ?? '').trim()
+    if (!videoId) return null   // fallthrough
+    const attrs = placeholderAttrs(node.attrs ?? {})
+    return `<div ${attrsToHtmlString(attrs)}><span>YouTube: ${escapeAttr(videoId)}</span></div>`
+  },
+}
+```
+
+#### 配線
+
+`update-ampless` が各プラグインの `./editor` モジュールから `tiptapNodeToMarkdown` と `tiptapNodeToHtml` の named export を読み取り（namespace import `* as` 経由）、両方の install に自動で配線する。**手動での配線は不要。** プラグインがいずれかのマップを export しない場合、生成ファイルの `?? {}` fallback が no-op になる。
+
+#### `markdown → html` 2-hop
+
+`markdown → html` の方向は `tiptapNodeToHtml` アダプターを 2-hop 経由で再利用する:
+
+1. `markdownToHtml(body)` — marked が markdown を HTML に変換。bare URL 行は `<p><a href="URL">URL</a></p>` になる。
+2. `generateJSON(html, extensions)` — tiptap が HTML を parse。プラグインの `Node.parseHTML` `tag: 'p'` rule が bare URL の paragraph を embed Node に昇格する。
+3. `tiptapToHtml(doc, { nodeAdapters })` — html アダプターが embed Node をプレースホルダー div に serialize する。
+
+つまりプラグインは `tiptap → html` アダプターを 1 つ export するだけでよく、`markdown → html` の方向は tiptap の parse rule を通して自動的に再利用される。**重複ロジックは不要。**
+
+#### Follow-up: public html walker（未実装）
+
+`format: 'html'` 投稿で、保存されたプレースホルダー div を公開ページで実 iframe として描画するためには、将来の capability で保存された html body を render 時に walk し、`data-ampless-*` flag を見て登録済プラグインの React renderer（= tiptap 投稿で `contentFields.tiptap` が使うのと同じ renderer）に置換する仕組みが必要。スケッチ:
+
+- 新 plugin capability `contentFields.html`: プレースホルダー flag attribute（例: `data-ampless-youtube`）を key にし、parse 済 div の attribute set から React node を返す。
+- Runtime: `renderBody` の `format: 'html'` ブランチが body を parse、`[data-ampless-*]` div を walk して登録済 renderer の output に置換、残りは raw HTML として emit。
+- Runtime 側の server-side HTML parser（現状なし、`parse5` / `htmlparser2` 等の小さなパーサーを選定する必要あり）。
+
+本 PR の scope 外（別 proposal として track）。当面は html-format 投稿のプレースホルダーは raw HTML として扱われ、公開ページで iframe 表示したい著者は `tiptap` か `markdown` で保存する。
+
 ### markdown → tiptap の復元
 
 editor Node が markdown へ bare URL line として serialise される場合、逆方向の復元は paste rule ではなく `Node.parseHTML()` で扱う必要がある。admin の `markdown → tiptap` format switch は、まず markdown を HTML に変換する。GFM autolink により bare URL line は `<p><a href="https://...">https://...</a></p>` になり、その HTML を tiptap が document として parse する。paste rule は user paste / typing event 用なので、この HTML parse 経路では発火しない。

package/docs/plugin-author-guide.md

@@ -1104,6 +1104,165 @@ 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.
 
+The `_editor-bootstrap.tsx` generated by `update-ampless` wires three
+install calls — extensions, markdown adapters, and html adapters:
+
+```tsx
+// app/(admin)/admin/_editor-bootstrap.tsx  (AUTO-GENERATED — do not edit)
+'use client'
+// AUTO-GENERATED by `npm run update-ampless`. Do not edit ...
+import { installAdminEditorExtensions, installAdminTiptapNodeMarkdown, installAdminTiptapNodeHtml } from '@ampless/admin/editor'
+import * as __ampless_plugin_x_embed_editor from '@ampless/plugin-x-embed/editor'
+import * as __ampless_plugin_youtube_editor from '@ampless/plugin-youtube/editor'
+
+export function EditorBootstrap({ children }: { children: React.ReactNode }) {
+  installAdminEditorExtensions([
+    __ampless_plugin_x_embed_editor.editorExtension,
+    __ampless_plugin_youtube_editor.editorExtension,
+  ])
+  installAdminTiptapNodeMarkdown([
+    __ampless_plugin_x_embed_editor.tiptapNodeToMarkdown ?? {},
+    __ampless_plugin_youtube_editor.tiptapNodeToMarkdown ?? {},
+  ])
+  installAdminTiptapNodeHtml([
+    __ampless_plugin_x_embed_editor.tiptapNodeToHtml ?? {},
+    __ampless_plugin_youtube_editor.tiptapNodeToHtml ?? {},
+  ])
+  return <>{children}</>
+}
+```
+
+### Lossless format-switch adapters (`tiptapNodeToMarkdown` + `tiptapNodeToHtml`)
+
+When the operator switches the post format in the admin UI (e.g. `tiptap →
+markdown` or `tiptap → html`), the admin must convert the body content. For
+standard prose nodes tiptap's built-in renderers handle this, but **atom
+nodes** (embed blocks like `amplessYoutube`) have no children — they fall
+through with empty output, silently dropping the embed.
+
+Two adapters fix both directions:
+
+| Adapter               | Direction                         | Output |
+| --------------------- | --------------------------------- | ------ |
+| `tiptapNodeToMarkdown`| `tiptap → markdown`               | bare URL line (e.g. `https://youtu.be/<id>`) |
+| `tiptapNodeToHtml`    | `tiptap → html`, `markdown → html`| canonical placeholder div |
+
+The three canonical body representations across format-switch are:
+
+| Format   | Canonical form |
+| -------- | -------------- |
+| tiptap   | `{ type: 'amplessYoutube', attrs: { videoId, start } }` Node |
+| markdown | bare `https://youtu.be/<id>` URL line |
+| html     | `<div data-ampless-youtube data-video-id="<id>" …>…</div>` |
+
+The placeholder div is the canonical HTML form for **admin format-switch
+interop only**: it is what `Node.renderHTML` emits, and what
+`Node.parseHTML`'s `tag: 'div[data-ampless-*]'` rule restores from, so
+that switching `tiptap ↔ markdown ↔ html` in the admin preserves embeds
+losslessly.
+
+**Public render of `format: 'html'` posts does NOT expand the
+placeholder.** Public render paths are format-specific: tiptap posts go
+through the React walker that consults the `contentFields.tiptap`
+registry (= real iframe for `amplessYoutube` Nodes); markdown posts go
+through the markdown walker that consults `contentFields.markdownUrl`
+(= real iframe for bare URL paragraphs); html posts pass through as raw
+HTML (`htmlPassthroughBlock`). For an html-format post that contains a
+placeholder div, the public page shows the literal placeholder, not an
+iframe — `publicHtmlForPost` only emits `beforeContent` / `afterContent`
+slots and does not transform the body.
+
+If you want the embed to render publicly, save the post as `tiptap` or
+`markdown` (= the format-switch round-trip restores the embed Node /
+bare URL line, then the matching public walker emits the iframe). The
+`html` format is treated as **raw HTML written by an engineer who wants
+full control** — the placeholder is a format-switch round-trip artefact,
+not a renderable embed reference. A future capability could add a public
+html walker that expands `data-ampless-*` placeholders to iframes; see
+the follow-up note at the end of this section.
+
+#### Adapter contract
+
+Both adapters have the same signature:
+
+```ts
+(node: TiptapRenderNode) => string | null
+```
+
+Return a **string** (including empty string `''`) to use your output.
+Return **`null`** to fall through to the default switch (useful for nodes
+you don't handle or for degenerate inputs like a missing video id).
+
+```ts
+// packages/plugin-youtube/src/editor.tsx
+import type { TiptapNodeMarkdownAdapters, TiptapNodeHtmlAdapters } from 'ampless'
+
+export const tiptapNodeToMarkdown: TiptapNodeMarkdownAdapters = {
+  amplessYoutube: (node) => {
+    const videoId = String(node.attrs?.videoId ?? '').trim()
+    if (!videoId) return null   // fall through
+    return `https://youtu.be/${videoId}`
+  },
+}
+
+export const tiptapNodeToHtml: TiptapNodeHtmlAdapters = {
+  amplessYoutube: (node) => {
+    const videoId = String(node.attrs?.videoId ?? '').trim()
+    if (!videoId) return null   // fall through
+    // placeholderAttrs() is a plugin-local helper that returns the same
+    // attribute dict used by Node.renderHTML — single source of truth.
+    const attrs = placeholderAttrs(node.attrs ?? {})
+    return `<div ${attrsToHtmlString(attrs)}><span>YouTube: ${escapeAttr(videoId)}</span></div>`
+  },
+}
+```
+
+#### Wiring
+
+`update-ampless` reads the `tiptapNodeToMarkdown` and `tiptapNodeToHtml`
+named exports from each plugin's `./editor` module (via namespace import `*
+as`) and wires them into both installs automatically — **no hand-wiring
+required**. If your plugin does not export one of the maps, the `?? {}`
+fallback in the generated file is a no-op.
+
+#### `markdown → html` 2-hop
+
+The `markdown → html` direction reuses the `tiptapNodeToHtml` adapter via
+a 2-hop:
+
+1. `markdownToHtml(body)` — marked converts the markdown body to HTML. Bare
+   URL lines become `<p><a href="URL">URL</a></p>`.
+2. `generateJSON(html, extensions)` — tiptap parses the HTML. Your plugin's
+   `Node.parseHTML` `tag: 'p'` rule promotes the bare-URL paragraph to the
+   embed Node.
+3. `tiptapToHtml(doc, { nodeAdapters })` — the html adapter serialises the
+   embed Node to the placeholder div.
+
+This means your plugin only needs to export the `tiptap → html` adapter once;
+the `markdown → html` direction reuses it automatically through tiptap's parse
+rules. **No duplicate logic is needed.**
+
+#### Follow-up: public html walker (not implemented)
+
+To make `format: 'html'` posts render placeholder divs as real iframes
+on the public page, a future capability would walk the saved html body
+on render, look up the `data-ampless-*` flag, and replace the placeholder
+with the registered plugin's React renderer (same renderer that
+`contentFields.tiptap` already uses for tiptap posts). Sketch:
+
+- New plugin capability `contentFields.html` keyed on the placeholder
+  flag attribute (e.g. `data-ampless-youtube`), returning a React node
+  from the parsed div's attribute set.
+- Runtime: `renderBody` for `format: 'html'` parses the body, walks
+  `[data-ampless-*]` divs, replaces each with the registered renderer's
+  output, and emits the rest as raw HTML.
+- Server-side HTML parsing in runtime (currently absent — would need
+  to pick a small parser like `parse5` or `htmlparser2`).
+
+Out of scope for the current PR (tracked as a separate proposal). For
+now, html-format posts treat placeholders as raw HTML and authors who
+want public iframes should save as `tiptap` or `markdown`.
+
 ### Markdown to tiptap restoration
 
 If an editor Node serializes to markdown as a bare URL line, the reverse

package/package.json

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