ampless 1.0.0-alpha.47 → 1.0.0-alpha.49

package/dist/index.d.ts

@@ -1072,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;
@@ -1639,6 +1681,34 @@ interface PostRevisionConnection {
     items: PostRevision[];
     nextToken?: string;
 }
+/**
+ * Lightweight row for admin list views — excludes body / metadata.
+ * Body fields (tiptap JSON, markdown source, etc.) can be tens of KB per post;
+ * projecting them out cuts per-post transfer size by 90%+ at scale.
+ *
+ * For list views that only need title / slug / status / dates / tags,
+ * use `listPostSummaries` instead of `listPosts`.
+ *
+ * Scale note: for single-site blogs (hundreds to low thousands of posts),
+ * full client-side fetch + sort/search is fast and eliminates GSI complexity.
+ * If a site grows to many thousands of posts, revisit with a
+ * (status, updatedAt) GSI + server-side pagination.
+ */
+interface PostSummary {
+    postId: string;
+    slug: string;
+    title: string;
+    excerpt?: string;
+    status: 'draft' | 'published';
+    publishedAt?: string;
+    updatedAt?: string;
+    tags: string[];
+}
+/** Options for `listPostSummaries`. */
+interface SummaryListOptions {
+    /** default 'all' */
+    status?: 'draft' | 'published' | 'all';
+}
 interface PostsProvider {
     list(opts?: ListOptions): Promise<Post[]>;
     get(slug: string): Promise<Post | null>;
@@ -1647,6 +1717,17 @@ interface PostsProvider {
     update(postId: string, data: Partial<Post>): Promise<Post>;
     remove(postId: string): Promise<void>;
     listPostHistory(postId: string, options?: ListPostHistoryOptions): Promise<PostRevisionConnection>;
+    /**
+     * Return lightweight summaries for all posts (no body / metadata).
+     * Implementations MUST page through all nextToken values to return the
+     * complete list — the admin list view depends on this for accurate search
+     * and sort.
+     *
+     * Optional: providers that do not implement this fall back to a best-effort
+     * single-page result via `list()` (see `listPostSummaries` fallback path).
+     * The admin provider always implements this.
+     */
+    listSummaries?(opts?: SummaryListOptions): Promise<PostSummary[]>;
 }
 declare function setPostsProvider(p: PostsProvider): void;
 declare function hasPostsProvider(): boolean;
@@ -1663,6 +1744,23 @@ declare function deletePost(postId: string): Promise<void>;
  * callers (e.g. the admin history panel) degrade gracefully.
  */
 declare function listPostHistory(postId: string, options?: ListPostHistoryOptions): Promise<PostRevisionConnection>;
+/**
+ * Return lightweight summaries for all posts (no body / metadata).
+ *
+ * Delegates to `provider.listSummaries()` when available — the admin
+ * provider implements this with a full nextToken loop and selectionSet
+ * projection, ensuring all posts are returned without fetching large body
+ * fields.
+ *
+ * **Fallback**: if the configured provider does not implement `listSummaries`,
+ * falls back to a single page from `provider.list({ status })`. This is
+ * best-effort only — it returns at most one page of results (no pagination).
+ * Providers that need complete summary lists MUST implement `listSummaries`.
+ * A `console.warn` is emitted once to make this visible.
+ *
+ * If no provider is configured, maps DUMMY_POSTS to summaries.
+ */
+declare function listPostSummaries(opts?: SummaryListOptions): Promise<PostSummary[]>;
 
 interface KvItem<T = unknown> {
     pk: string;
@@ -1925,4 +2023,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 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 };
+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 PostSummary, 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, type SummaryListOptions, 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, listPostSummaries, listPosts, listSiteSettings, mimeTypeFor, parseColorPair, parseLinkList, pickDefaultEntrypoint, resolveLocalized, resolvePluginSettings, resolveThemeValues, setKvStore, setPostsProvider, setSiteSetting, stringifyLinkList, stripCommonPrefix, themeSettingKey, unflattenSettings, updatePost, validateBundle, validateBundlePath, validatePluginSettingValue, validatePublicAssetKey, validateThemeValue };

package/dist/index.js

@@ -47,6 +47,7 @@ var DUMMY_POSTS = [
 
 // src/core.ts
 var provider = null;
+var warnedSummaryFallback = false;
 function setPostsProvider(p) {
   provider = p;
 }
@@ -87,6 +88,35 @@ async function listPostHistory(postId, options) {
   if (!provider) return { items: [] };
   return provider.listPostHistory(postId, options);
 }
+async function listPostSummaries(opts) {
+  const status = opts?.status ?? "all";
+  if (!provider) {
+    return dummyList({ status }).map(postToSummary);
+  }
+  if (provider.listSummaries) {
+    return provider.listSummaries(opts);
+  }
+  if (!warnedSummaryFallback) {
+    warnedSummaryFallback = true;
+    console.warn(
+      "[ampless] listPostSummaries: provider does not implement listSummaries; falling back to a single-page best-effort via list(). Complete listings require the provider to implement listSummaries."
+    );
+  }
+  const posts = await provider.list({ status });
+  return posts.map(postToSummary);
+}
+function postToSummary(p) {
+  return {
+    postId: p.postId,
+    slug: p.slug,
+    title: p.title,
+    excerpt: p.excerpt,
+    status: p.status,
+    publishedAt: p.publishedAt,
+    updatedAt: p.updatedAt,
+    tags: p.tags ?? []
+  };
+}
 
 // src/kv.ts
 var store = null;
@@ -799,6 +829,7 @@ export {
   isTagListUrl,
   isValidPluginKey,
   listPostHistory,
+  listPostSummaries,
   listPosts,
   listSiteSettings,
   mimeTypeFor,

package/docs/plugin-author-guide.ja.md

@@ -896,9 +896,9 @@ operator が admin UI でポストのフォーマットを切り替える場合
 
 プレースホルダー 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 を変換しない。
+**`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 を公開ページで実際に描画させたい場合は、投稿を `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 を参照。
+embed node を持つが `htmlPlaceholder` を**宣言しない** plugin は従来挙動を維持する: `format: 'html'` 投稿の公開描画ではプレースホルダー div がリテラルにそのまま出力される（内側の正規 URL link は clickable なので graceful に degrade する）。その場合に iframe を得るには `tiptap` または `markdown` 形式で保存する。
 
 #### アダプターの契約
 
@@ -927,7 +927,15 @@ export const tiptapNodeToHtml: TiptapNodeHtmlAdapters = {
     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>`
+    // 内側のコンテンツは 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>`
   },
 }
 ```
@@ -946,15 +954,52 @@ export const tiptapNodeToHtml: TiptapNodeHtmlAdapters = {
 
 つまりプラグインは `tiptap → html` アダプターを 1 つ export するだけでよく、`markdown → html` の方向は tiptap の parse rule を通して自動的に再利用される。**重複ロジックは不要。**
 
-#### Follow-up: public html walker（未実装）
+#### Public html walker: `htmlPlaceholder`
 
-`format: 'html'` 投稿で、保存されたプレースホルダー div を公開ページで実 iframe として描画するためには、将来の capability で保存された html body を render 時に walk し、`data-ampless-*` flag を見て登録済プラグインの React renderer（= tiptap 投稿で `contentFields.tiptap` が使うのと同じ renderer）に置換する仕組みが必要。スケッチ:
+`format: 'html'` 投稿のプレースホルダー div を公開ページで実 embed として描画するには、既存の `contentFields` の `tiptap` entry に **`htmlPlaceholder`** 宣言を追加する。**新しい renderer は書かない** — walker は tiptap entry が既に使う `render(node, ctx)` をそのまま呼ぶので、3 形式（tiptap / markdown / html）すべてが 1 個の renderer に到達し、描画が divergence しない。
 
-- 新 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` 等の小さなパーサーを選定する必要あり）。
+```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 を注入する。
 
-本 PR の scope 外（別 proposal として track）。当面は html-format 投稿のプレースホルダーは raw HTML として扱われ、公開ページで iframe 表示したい著者は `tiptap` か `markdown` で保存する。
+**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 の復元
 

package/docs/plugin-author-guide.md

@@ -1161,25 +1161,27 @@ interop only**: it is what `Node.renderHTML` emits, and what
 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.
+**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
 
@@ -1212,7 +1214,16 @@ export const tiptapNodeToHtml: TiptapNodeHtmlAdapters = {
     // 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>`
+    // 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>`
   },
 }
 ```
@@ -1242,26 +1253,82 @@ 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`.
+#### 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
 

package/package.json

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