ampless 1.0.0-alpha.46 → 1.0.0-alpha.48

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
@@ -1048,6 +1072,48 @@ type ContentFieldRenderer = {
     kind: 'tiptap';
     nodeType: string;
     render(node: TiptapRenderNode, ctx: PluginPublicRenderContext): ReactNode;
+    /**
+     * Opt-in: expand this node's canonical placeholder div when it
+     * appears in a `format: 'html'` post body on public render.
+     *
+     * The admin's `tiptap → html` format switch serialises an embed
+     * node (e.g. `amplessYoutube`) to its canonical placeholder div
+     * (`<div data-ampless-youtube data-video-id="…"><a href="…">…</a></div>`,
+     * via the `tiptapNodeToHtml` adapter). Without `htmlPlaceholder`,
+     * the public renderer of a `format: 'html'` post emits that div
+     * literally — the placeholder shows as a bare div + link instead
+     * of the live embed. (This was the documented limitation from the
+     * canonical-html-embed work; declaring `htmlPlaceholder` resolves
+     * it.)
+     *
+     * When declared, the runtime's public html walker finds each
+     * **top-level** element carrying `flagAttr`, builds a
+     * `TiptapRenderNode { type: nodeType, attrs: attrsFromElement(attribs) }`,
+     * and calls this same `render` — so the `tiptap`, `markdown`, and
+     * `html` formats all reach one renderer (no per-format divergence).
+     *
+     * - `flagAttr` is the marker attribute (e.g.
+     *   `'data-ampless-youtube'`). It is **matched case-insensitively**:
+     *   the runtime lowercases it at registration because htmlparser2
+     *   lowercases HTML attribute names while parsing, so declaring
+     *   `'data-My-Embed'` still matches `<div data-my-embed>` /
+     *   `<div DATA-MY-EMBED>`.
+     * - `attrsFromElement` converts the div's HTML attributes (already
+     *   lowercased by the parser) into the tiptap node `attrs` that
+     *   `render` expects, with the correct types — e.g. a
+     *   `data-start="30"` string must become the `number 30` that
+     *   `render` reads.
+     *
+     * Only top-level placeholders expand; divs nested inside
+     * `<blockquote>` / `<li>` / etc. stay literal. If `attrsFromElement`
+     * or `render` throws, the runtime warns and falls back to the raw
+     * placeholder slice (the embedded link stays clickable) rather than
+     * dropping the engineer-authored content.
+     */
+    htmlPlaceholder?: {
+        flagAttr: string;
+        attrsFromElement(attribs: Readonly<Record<string, string>>): Record<string, unknown>;
+    };
 } | {
     kind: 'markdown-url';
     pattern: RegExp;
@@ -1901,4 +1967,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,159 @@ 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'` の公開描画は、plugin が `htmlPlaceholder` を宣言していればプレースホルダーを展開する。** 公開描画の 3 経路すべてが同じ `contentFields.tiptap` renderer に到達する: tiptap 投稿は React walker が `contentFields.tiptap` registry を参照（= `amplessYoutube` Node を実際の iframe に変換）、markdown 投稿は markdown walker が `contentFields.markdownUrl` を参照（= bare URL paragraph を実際の iframe に変換）、html 投稿は **public html walker** が `contentFields.htmlPlaceholder` を参照（= top-level の `<div data-ampless-youtube …>` プレースホルダーを実際の iframe に変換）。上の `tiptapNodeToHtml` アダプターは **admin format-switch** の交換形式のみを司り、その形式を公開描画時に展開させるのは `htmlPlaceholder` の宣言である（契約は下記の `htmlPlaceholder` セクションを参照）。`publicHtmlForPost` は従来どおり `beforeContent` / `afterContent` slot のみ提供する capability であり、body を変換しない。
+
+embed node を持つが `htmlPlaceholder` を**宣言しない** plugin は従来挙動を維持する: `format: 'html'` 投稿の公開描画ではプレースホルダー div がリテラルにそのまま出力される（内側の正規 URL link は clickable なので graceful に degrade する）。その場合に iframe を得るには `tiptap` または `markdown` 形式で保存する。
+
+#### アダプターの契約
+
+両アダプターは同じシグネチャを持つ:
+
+```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 ?? {})
+    // 内側のコンテンツは editor 用視覚 label (`<span>YouTube: id</span>`、
+    // Node.renderHTML 専用) ではなく URL link にする。`format: 'html'` の
+    // 公開描画ではこの body をリテラル表示するため editor 用 label が漏れる
+    // のを防ぐ。viewer 側で iframe 展開されない場合でもクリック可能な link が
+    // 残り graceful degradation する。markdown 正規形 (bare URL line) と
+    // 対応する形式。parseHTML は `data-video-id` 属性を読むため内側コンテンツは
+    // round-trip と無関係。
+    const url = `https://youtu.be/${videoId}`
+    return `<div ${attrsToHtmlString(attrs)}><a href="${escapeAttr(url)}">${escapeAttr(url)}</a></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 を通して自動的に再利用される。**重複ロジックは不要。**
+
+#### Public html walker: `htmlPlaceholder`
+
+`format: 'html'` 投稿のプレースホルダー div を公開ページで実 embed として描画するには、既存の `contentFields` の `tiptap` entry に **`htmlPlaceholder`** 宣言を追加する。**新しい renderer は書かない** — walker は tiptap entry が既に使う `render(node, ctx)` をそのまま呼ぶので、3 形式（tiptap / markdown / html）すべてが 1 個の renderer に到達し、描画が divergence しない。
+
+```ts
+// packages/plugin-youtube/src/index.tsx
+contentFields: [
+  {
+    kind: 'tiptap',
+    nodeType: 'amplessYoutube',
+    render: (node) => {
+      const videoId = String(node.attrs?.videoId ?? '')
+      const startRaw = node.attrs?.start
+      const start =
+        typeof startRaw === 'number' && Number.isFinite(startRaw) ? startRaw : undefined
+      return <YouTubeEmbed videoId={videoId} start={start} />
+    },
+    htmlPlaceholder: {
+      // top-level プレースホルダー div を識別する marker attribute。
+      flagAttr: 'data-ampless-youtube',
+      // div の HTML 属性を render が期待する tiptap node attrs に変換する
+      // — 型も正しく。walker は型を知らないのでここで変換する
+      // （例: data-start string → number）。
+      attrsFromElement: (attribs) => {
+        const start = Number(attribs['data-start'])
+        return {
+          videoId: attribs['data-video-id'] ?? '',
+          start: Number.isFinite(start) ? start : undefined,
+        }
+      },
+    },
+  },
+  // …markdown-url entry は変更なし…
+]
+```
+
+`format: 'html'` 投稿の公開描画時、runtime は body を server-side で parse し（`htmlparser2`）、`flagAttr` を持つ **top-level** element ごとに `{ type: nodeType, attrs: attrsFromElement(attribs) }` node を組んで `render(node, ctx)` を呼ぶ。それ以外はすべて **元文字列の slice**（byte 単位で完全保存、DOM の再シリアライズなし）として passthrough する。
+
+把握すべき制約:
+
+- **top-level のみ。** `<blockquote>` / `<li>` 等の内側に nest したプレースホルダー div はリテラルのまま — editor の body-level-only な `parseHTML` fallback と整合。展開されるのは depth-0 の element のみ。
+- **`flagAttr` は case-insensitive で照合される。** htmlparser2 は parse 時に HTML 属性名を小文字化し、runtime は登録時に `flagAttr` を小文字化するため、`<div DATA-AMPLESS-YOUTUBE …>` も `<div data-ampless-youtube …>` も展開される。`flagAttr` は任意の属性名でよい — site-local plugin は `data-my-embed` を使える。固定の `data-ampless` prefix 要件はない。
+- **graceful degradation。** `attrsFromElement` または `render` が throw した場合、runtime は `console.warn` を出力し **元のプレースホルダー slice**（内側の正規 URL link は clickable のまま）に fallback する。engineer が書いた本文を消さない。
+- **page-level script。** embed が third-party script を要する場合（例: x.com の `widgets.js`）、`publicPostScript` / 検知ヘルパーもプレースホルダー形式を認識する必要がある。`plugin-x-embed` の `hasTweetIn` は `format: 'html'` body 内で `twitter-tweet` と `data-ampless-tweet` の両方を match させ、展開された blockquote を hydrate するため widgets.js を注入する。
+
+**wrapper 境界の変化。** プレースホルダーを含まない `format: 'html'` 投稿は単一の wrapper `<div>` として出力される（fast path — 従来の raw passthrough と markup 完全一致）。プレースホルダーを**含む**投稿は **複数の wrapper div と React embed の兄弟列が交互に並ぶ**構造になる: 各 raw chunk 内の bytes は正確に保存されるが、wrapper 境界は移動する。body 全体を 1 個の wrapper で囲む前提の direct-child / adjacent-sibling CSS selector は従来と同じには効かない。これは embed を in-place 展開するための許容トレードオフ。
+
 ### 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,232 @@ 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 expands the placeholder when
+the plugin declares `htmlPlaceholder`.** All three public render paths
+reach the same `contentFields.tiptap` renderer: 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 go through the **public html walker**
+that consults `contentFields.htmlPlaceholder` (= real iframe for
+top-level `<div data-ampless-youtube …>` placeholders). The
+`tiptapNodeToHtml` adapter above only governs the **admin format-switch**
+interchange form — declaring `htmlPlaceholder` is what makes the public
+html walker expand that form on render. (See the dedicated
+`htmlPlaceholder` section below for the contract.) `publicHtmlForPost`
+still only emits `beforeContent` / `afterContent` slots and does not
+transform the body.
+
+A plugin that ships an embed node but does **not** declare
+`htmlPlaceholder` keeps the old behaviour: the placeholder div is shipped
+literally on public render of `format: 'html'` posts (the inner canonical
+URL link is still clickable, so it degrades gracefully). Save as `tiptap`
+or `markdown` to get the iframe in that case.
+
+#### 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 ?? {})
+    // Inner content is the canonical URL as a clickable link, not the
+    // editor's visual label `<span>YouTube: id</span>`. Public render of
+    // `format: 'html'` posts shows this content literally; an editor
+    // label would leak. The URL link gracefully degrades — viewers
+    // without iframe expansion still get a clickable link, and it
+    // mirrors the markdown canonical form. parseHTML reads the
+    // `data-video-id` attribute, so the inner content is irrelevant
+    // for round-trip.
+    const url = `https://youtu.be/${videoId}`
+    return `<div ${attrsToHtmlString(attrs)}><a href="${escapeAttr(url)}">${escapeAttr(url)}</a></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.**
+
+#### Public html walker: `htmlPlaceholder`
+
+To make `format: 'html'` posts render placeholder divs as real embeds on
+the public page, add an **`htmlPlaceholder`** declaration to your existing
+`contentFields` `tiptap` entry. You write **no new renderer** — the walker
+calls the same `render(node, ctx)` your tiptap entry already uses, so all
+three formats (tiptap / markdown / html) reach one renderer with no
+divergence.
+
+```ts
+// packages/plugin-youtube/src/index.tsx
+contentFields: [
+  {
+    kind: 'tiptap',
+    nodeType: 'amplessYoutube',
+    render: (node) => {
+      const videoId = String(node.attrs?.videoId ?? '')
+      const startRaw = node.attrs?.start
+      const start =
+        typeof startRaw === 'number' && Number.isFinite(startRaw) ? startRaw : undefined
+      return <YouTubeEmbed videoId={videoId} start={start} />
+    },
+    htmlPlaceholder: {
+      // The marker attribute that flags a top-level placeholder div.
+      flagAttr: 'data-ampless-youtube',
+      // Convert the div's HTML attributes into the tiptap node `attrs`
+      // your `render` expects — WITH the right types. The walker is
+      // type-agnostic, so coerce here (e.g. data-start string → number).
+      attrsFromElement: (attribs) => {
+        const start = Number(attribs['data-start'])
+        return {
+          videoId: attribs['data-video-id'] ?? '',
+          start: Number.isFinite(start) ? start : undefined,
+        }
+      },
+    },
+  },
+  // …markdown-url entry unchanged…
+]
+```
+
+On public render of a `format: 'html'` post, the runtime parses the body
+server-side (`htmlparser2`), finds each **top-level** element carrying
+`flagAttr`, builds a `{ type: nodeType, attrs: attrsFromElement(attribs) }`
+node, and calls `render(node, ctx)`. Everything else passes through as the
+**original-string slices** (byte-for-byte; no DOM re-serialisation).
+
+Constraints worth knowing:
+
+- **Top-level only.** Placeholder divs nested inside `<blockquote>`,
+  `<li>`, etc. stay literal — consistent with the editor's body-level-only
+  `parseHTML` fallback. Only depth-0 elements expand.
+- **`flagAttr` is matched case-insensitively.** htmlparser2 lowercases
+  HTML attribute names while parsing, and the runtime lowercases your
+  `flagAttr` at registration, so `<div DATA-AMPLESS-YOUTUBE …>` and
+  `<div data-ampless-youtube …>` both expand. `flagAttr` can be any
+  attribute name — a site-local plugin may use `data-my-embed`; there is
+  no fixed `data-ampless` prefix requirement.
+- **Graceful degradation.** If `attrsFromElement` or `render` throws, the
+  runtime logs a `console.warn` and falls back to the **raw placeholder
+  slice** (the inner canonical URL link stays clickable) rather than
+  dropping the engineer-authored content.
+- **Page-level scripts.** If your embed needs a third-party script (e.g.
+  x.com's `widgets.js`), your `publicPostScript` / detection helper must
+  also recognise the placeholder form. `plugin-x-embed`'s `hasTweetIn`
+  matches both `twitter-tweet` and `data-ampless-tweet` in `format: 'html'`
+  bodies so widgets.js is injected for the expanded blockquote to hydrate.
+
+**Wrapper-boundary change.** A placeholder-free `format: 'html'` post is
+emitted as a single wrapper `<div>` (the fast path — markup-identical to
+the previous raw passthrough). A post **with** placeholders becomes
+**multiple wrapper divs interleaved with the React embed siblings**: the
+bytes inside each raw chunk are preserved exactly, but the wrapper
+boundaries shift. Direct-child / adjacent-sibling CSS selectors that
+assumed one wrapper around the whole body will not match the same way.
+This is the accepted trade-off for expanding embeds in-place.
+
 ### 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.48",
   "description": "Serverless CMS for AWS Amplify",
   "license": "MIT",
   "type": "module",