ampless 1.0.0-alpha.47 → 1.0.0-alpha.48

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;

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.48",
   "description": "Serverless CMS for AWS Amplify",
   "license": "MIT",
   "type": "module",