create-ampless 1.0.0-alpha.137 → 1.0.0-alpha.139

package/dist/index.js

@@ -2230,7 +2230,7 @@ async function regenerateEditorBootstrap(destDir, projectPkg) {
   lines.push("// editor extension, add / remove the corresponding @ampless/plugin-...");
   lines.push("// entry in your project's package.json (and register it in cms.config.ts");
   lines.push("// for runtime).", "");
-  lines.push("import { installAdminEditorExtensions, installAdminTiptapNodeMarkdown } from '@ampless/admin/editor'");
+  lines.push("import { installAdminEditorExtensions, installAdminTiptapNodeMarkdown, installAdminTiptapNodeHtml } from '@ampless/admin/editor'");
   const identifiers = [];
   const seen = /* @__PURE__ */ new Map();
   for (const p3 of installedPlugins) {
@@ -2251,6 +2251,7 @@ async function regenerateEditorBootstrap(destDir, projectPkg) {
   if (identifiers.length === 0) {
     lines.push("  installAdminEditorExtensions([])");
     lines.push("  installAdminTiptapNodeMarkdown([])");
+    lines.push("  installAdminTiptapNodeHtml([])");
   } else {
     lines.push("  installAdminEditorExtensions([");
     for (const id of identifiers) lines.push(`    ${id}.editorExtension,`);
@@ -2258,6 +2259,9 @@ async function regenerateEditorBootstrap(destDir, projectPkg) {
     lines.push("  installAdminTiptapNodeMarkdown([");
     for (const id of identifiers) lines.push(`    ${id}.tiptapNodeToMarkdown ?? {},`);
     lines.push("  ])");
+    lines.push("  installAdminTiptapNodeHtml([");
+    for (const id of identifiers) lines.push(`    ${id}.tiptapNodeToHtml ?? {},`);
+    lines.push("  ])");
   }
   lines.push("  return <>{children}</>");
   lines.push("}");

package/dist/templates/_shared/docs/plugin-author-guide.ja.md

@@ -848,6 +848,113 @@ 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
+import type { TiptapNodeMarkdownAdapters, TiptapNodeHtmlAdapters } from 'ampless'
+
+export const tiptapNodeToMarkdown: TiptapNodeMarkdownAdapters = {
+  amplessYoutube: (node) => {
+    const videoId = String(node.attrs?.videoId ?? '').trim()
+    if (!videoId) return null
+    return `https://youtu.be/${videoId}`
+  },
+}
+
+export const tiptapNodeToHtml: TiptapNodeHtmlAdapters = {
+  amplessYoutube: (node) => {
+    const videoId = String(node.attrs?.videoId ?? '').trim()
+    if (!videoId) return null
+    const attrs = placeholderAttrs(node.attrs ?? {})
+    return `<div ${attrsToHtmlString(attrs)}><span>YouTube: ${escapeAttr(videoId)}</span></div>`
+  },
+}
+```
+
+#### 配線
+
+`update-ampless` が各プラグインの `./editor` モジュールから `tiptapNodeToMarkdown` と `tiptapNodeToHtml` の named export を読み取り、両方の 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/dist/templates/_shared/docs/plugin-author-guide.md

@@ -1104,6 +1104,163 @@ 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
+    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/dist/templates/_shared/package.json

@@ -26,21 +26,21 @@
     "@tiptap/pm": "^3.23.6",
     "@tiptap/react": "^3.23.6",
     "@tiptap/starter-kit": "^3.23.6",
-    "@ampless/plugin-analytics-ga4": "^0.2.0-alpha.30",
-    "@ampless/plugin-cookie-consent": "^0.1.0-alpha.21",
-    "@ampless/plugin-gtm": "^0.2.0-alpha.29",
-    "@ampless/plugin-og-image": "^0.2.0-alpha.46",
-    "@ampless/plugin-plausible": "^0.2.0-alpha.29",
-    "@ampless/plugin-reading-time": "^0.1.0-alpha.19",
-    "@ampless/plugin-rss": "^0.2.0-alpha.46",
-    "@ampless/plugin-schema-jsonld": "^0.1.1-alpha.25",
-    "@ampless/plugin-seo": "^0.2.0-alpha.46",
-    "@ampless/plugin-webhook": "^0.2.0-alpha.47",
-    "@ampless/admin": "^1.0.0-alpha.79",
-    "@ampless/backend": "^1.0.0-alpha.68",
-    "@ampless/runtime": "^1.0.0-alpha.55",
+    "@ampless/plugin-analytics-ga4": "^0.2.0-alpha.31",
+    "@ampless/plugin-cookie-consent": "^0.1.0-alpha.22",
+    "@ampless/plugin-gtm": "^0.2.0-alpha.30",
+    "@ampless/plugin-og-image": "^0.2.0-alpha.47",
+    "@ampless/plugin-plausible": "^0.2.0-alpha.30",
+    "@ampless/plugin-reading-time": "^0.1.0-alpha.20",
+    "@ampless/plugin-rss": "^0.2.0-alpha.47",
+    "@ampless/plugin-schema-jsonld": "^0.1.1-alpha.26",
+    "@ampless/plugin-seo": "^0.2.0-alpha.47",
+    "@ampless/plugin-webhook": "^0.2.0-alpha.48",
+    "@ampless/admin": "^1.0.0-alpha.80",
+    "@ampless/backend": "^1.0.0-alpha.69",
+    "@ampless/runtime": "^1.0.0-alpha.56",
     "@digital-go-jp/tailwind-theme-plugin": "^0.3.4",
-    "ampless": "^1.0.0-alpha.46",
+    "ampless": "^1.0.0-alpha.47",
     "aws-amplify": "^6.17.0",
     "class-variance-authority": "^0.7.1",
     "clsx": "^2.1.1",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-ampless",
-  "version": "1.0.0-alpha.137",
+  "version": "1.0.0-alpha.139",
   "description": "Create a new ampless project",
   "license": "MIT",
   "type": "module",