ampless 1.0.0-beta.53 → 1.0.0-beta.55

package/dist/index.d.ts

@@ -17,12 +17,20 @@ type SiteSettingsEventType = 'site.settings.updated';
  */
 type PostIndexEventType = 'post.index.refresh';
 type EventType = ContentEventType | MediaEventType | SiteSettingsEventType | PostIndexEventType;
-/** Minimal projection of a Post item carried in events (no body, to keep payloads small). */
+/**
+ * Minimal projection of a Post item carried in events (no body, to keep
+ * payloads small). `format` / `excerpt` are included so the denormalized
+ * PostTag index can render tag-page summaries faithfully — without them the
+ * `listPostsByTag` resolver can't know a post's real format and would
+ * mislabel non-markdown posts.
+ */
 interface ContentEventPayload {
     postId: string;
     slug: string;
     title: string;
     status: 'draft' | 'published';
+    format?: ContentFormat;
+    excerpt?: string;
     publishedAt?: string;
     tags?: string[];
 }
@@ -1352,6 +1360,12 @@ interface AmplessPlugin {
      * capability.
      */
     publicPostScript?(post: Post, ctx: PluginPublicRenderContext): readonly PublicPostScriptDescriptor[];
+    /**
+     * Server-safe map of TipTap nodeType -> markdown serialiser, used by the
+     * public runtime (postToMarkdown) — same shape the admin registry consumes.
+     * Keep implementations free of '@tiptap/*' imports and 'use client'.
+     */
+    tiptapNodeToMarkdown?: TiptapNodeMarkdownAdapters;
     /**
      * Dynamic OG image renderer. The dispatcher route (e.g.
      * `app/og/[slug]/route.ts`) reads this and feeds the element into

package/dist/index.js

@@ -258,6 +258,16 @@ function definePlugin(p) {
       );
     }
   }
+  if (p.contentFields) {
+    for (const field of p.contentFields) {
+      if (field.kind !== "tiptap") continue;
+      if (typeof p.tiptapNodeToMarkdown?.[field.nodeType] !== "function") {
+        console.warn(
+          `[ampless] Plugin "${p.name}": contentFields declares tiptap nodeType "${field.nodeType}" but tiptapNodeToMarkdown has no adapter for it. The public runtime's markdown export will fall back to the default switch for this node. Add an adapter to tiptapNodeToMarkdown or ignore this if the fallback output is acceptable.`
+        );
+      }
+    }
+  }
   if (p.trust_level === "privileged") {
     const hasHooks = p.hooks && Object.keys(p.hooks).length > 0 || (p.capabilities?.includes("eventHooks") ?? false);
     if (hasHooks) {
@@ -529,6 +539,11 @@ function compareRows(a, b, sort) {
       return b.title.localeCompare(a.title);
     case "title-asc":
       return a.title.localeCompare(b.title);
+    default: {
+      const _exhaustive = sort;
+      void _exhaustive;
+      return 0;
+    }
   }
 }
 function compareOptionalIso(a, b, direction) {
@@ -766,6 +781,11 @@ function validateThemeValue(field, raw) {
       const sanitized = v.replace(/[\x00-\x1f<>]/g, "");
       return sanitized.length <= max ? sanitized : sanitized.slice(0, max);
     }
+    default: {
+      const _exhaustive = field;
+      void _exhaustive;
+      return null;
+    }
   }
 }
 var DANGEROUS_URL_RE = /^\s*(javascript|data|vbscript):/i;

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

@@ -186,6 +186,7 @@ interface AmplessPlugin {
   publicBodyEnd?(ctx): readonly PublicBodyDescriptor[]
   publicBodyForPost?(post: Post, ctx): readonly PublicPostBodyDescriptor[]
   publicHtmlForPost?(post: Post, ctx): readonly PublicPostHtmlDescriptor[]
+  tiptapNodeToMarkdown?: TiptapNodeMarkdownAdapters  // server-safe markdown export adapters
   ogImage?: OgImageConfig
   settings?: {
     public?: readonly PluginSettingField[]
@@ -884,6 +885,48 @@ export function EditorBootstrap({ children }: { children: React.ReactNode }) {
 }
 ```
 
+### アダプターの置き場所: `./editor.tsx` ではなく `./adapters.ts`
+
+`./editor.tsx` は `'use client'` かつ `@tiptap/core` を import している —
+admin バンドルには問題ないが、server コード（や将来の `postToMarkdown`
+public runtime）からこれを import すると両方を巻き込んでしまう。アダプター
+（および `Node.renderHTML` と共有する `placeholderAttrs` のような plain
+object ヘルパ）は、tiptap 非依存の別モジュール `./adapters.ts` に置き、
+`./editor.tsx` からは 2 つの named symbol を **re-export** する:
+
+```ts
+// packages/plugin-youtube/src/adapters.ts — 'use client' なし、@tiptap/* import なし
+export const tiptapNodeToMarkdown: TiptapNodeMarkdownAdapters = { /* ... */ }
+export const tiptapNodeToHtml: TiptapNodeHtmlAdapters = { /* ... */ }
+```
+
+```ts
+// packages/plugin-youtube/src/editor.tsx
+export { tiptapNodeToMarkdown, tiptapNodeToHtml } from './adapters.js'
+```
+
+この re-export により `update-ampless` の codegen 契約は無改修で維持される
+（下記「配線」の通り、`./editor` の namespace import から `ns.tiptapNodeToMarkdown ?? {}` /
+`ns.tiptapNodeToHtml ?? {}` を読む挙動は変わらない）。同時に server 側
+entry（`./index.tsx`）も同じアダプターを `./adapters.js` から import して
+manifest に設定できる:
+
+```ts
+// packages/plugin-youtube/src/index.tsx
+import { tiptapNodeToMarkdown } from './adapters.js'
+
+export default function youtubePlugin(opts = {}) {
+  return definePlugin({
+    // ...
+    tiptapNodeToMarkdown,   // AmplessPlugin.tiptapNodeToMarkdown — server 側 canonical
+  })
+}
+```
+
+`definePlugin()` は `contentFields` の `kind: 'tiptap'` エントリの
+`nodeType` に対応する `tiptapNodeToMarkdown` のキーが無い場合に warn する
+— 両方をセットで宣言し、warning が出ない状態を保つ。
+
 ### フォーマット切り替えの可逆アダプター（`tiptapNodeToMarkdown` + `tiptapNodeToHtml`）
 
 operator が admin UI でポストのフォーマットを切り替える場合（例: `tiptap → markdown`、`tiptap → html`）、admin はボディコンテンツを変換する必要がある。通常の prose node は tiptap の built-in レンダラーで処理されるが、**atom node**（`amplessYoutube` のような embed ブロック）は子要素を持たず、children が空のまま fallthrough し、embed が無音で消えてしまう。
@@ -920,7 +963,7 @@ embed node を持つが `htmlPlaceholder` を**宣言しない** plugin は従
 **文字列**（空文字 `''` も含む）を返すと、その出力を使う。**`null`** を返すとデフォルトの switch へ fallthrough する（対応しない node や video id が欠損している場合などに使う）。
 
 ```ts
-// packages/plugin-youtube/src/editor.tsx
+// packages/plugin-youtube/src/adapters.ts
 import type { TiptapNodeMarkdownAdapters, TiptapNodeHtmlAdapters } from 'ampless'
 
 export const tiptapNodeToMarkdown: TiptapNodeMarkdownAdapters = {
@@ -951,7 +994,7 @@ export const tiptapNodeToHtml: TiptapNodeHtmlAdapters = {
 
 #### 配線
 
-`update-ampless` が各プラグインの `./editor` モジュールから `tiptapNodeToMarkdown` と `tiptapNodeToHtml` の named export を読み取り（namespace import `* as` 経由）、両方の install に自動で配線する。**手動での配線は不要。** プラグインがいずれかのマップを export しない場合、生成ファイルの `?? {}` fallback が no-op になる。
+`update-ampless` が各プラグインの `./editor` モジュールから `tiptapNodeToMarkdown` と `tiptapNodeToHtml` の named export を読み取り（namespace import `* as` 経由）、両方の install に自動で配線する。**手動での配線は不要。** プラグインがいずれかのマップを export しない場合、生成ファイルの `?? {}` fallback が no-op になる。上記の通り、`./editor` が re-export するこれらの export は通常 `./adapters.ts` に実装されている — codegen は `./editor` の namespace から到達可能であることだけを見ており、定義場所は問わない。
 
 #### `markdown → html` 2-hop
 

package/docs/plugin-author-guide.md

@@ -214,6 +214,7 @@ interface AmplessPlugin {
   publicBodyEnd?(ctx): readonly PublicBodyDescriptor[]
   publicBodyForPost?(post: Post, ctx): readonly PublicPostBodyDescriptor[]
   publicHtmlForPost?(post: Post, ctx): readonly PublicPostHtmlDescriptor[]
+  tiptapNodeToMarkdown?: TiptapNodeMarkdownAdapters  // server-safe markdown export adapters
   ogImage?: OgImageConfig
   settings?: {
     public?: readonly PluginSettingField[]
@@ -1142,6 +1143,48 @@ export function EditorBootstrap({ children }: { children: React.ReactNode }) {
 }
 ```
 
+### Where the adapters live: `./adapters.ts`, not `./editor.tsx`
+
+`./editor.tsx` carries `'use client'` and imports `@tiptap/core` — fine for
+the admin bundle, but importing it from server code (or the future
+`postToMarkdown` public runtime) would drag both along. Put the adapters
+(and any plain-object helpers they share with `Node.renderHTML`, like
+`placeholderAttrs`) in a separate, tiptap-free module — `./adapters.ts` —
+and have `./editor.tsx` **re-export** the two named symbols:
+
+```ts
+// packages/plugin-youtube/src/adapters.ts — no 'use client', no @tiptap/* import
+export const tiptapNodeToMarkdown: TiptapNodeMarkdownAdapters = { /* ... */ }
+export const tiptapNodeToHtml: TiptapNodeHtmlAdapters = { /* ... */ }
+```
+
+```ts
+// packages/plugin-youtube/src/editor.tsx
+export { tiptapNodeToMarkdown, tiptapNodeToHtml } from './adapters.js'
+```
+
+The re-export keeps `update-ampless`'s codegen contract intact (it still
+reads `ns.tiptapNodeToMarkdown ?? {}` / `ns.tiptapNodeToHtml ?? {}` from a
+namespace import of `./editor` — see Wiring below) while also letting your
+server entry (`./index.tsx`) import the same adapter from `./adapters.js`
+and set it on the manifest:
+
+```ts
+// packages/plugin-youtube/src/index.tsx
+import { tiptapNodeToMarkdown } from './adapters.js'
+
+export default function youtubePlugin(opts = {}) {
+  return definePlugin({
+    // ...
+    tiptapNodeToMarkdown,   // AmplessPlugin.tiptapNodeToMarkdown — server-side canonical
+  })
+}
+```
+
+`definePlugin()` warns if a `contentFields` `kind: 'tiptap'` entry's
+`nodeType` has no matching key in `tiptapNodeToMarkdown` — declare both
+together so the warning stays silent.
+
 ### Lossless format-switch adapters (`tiptapNodeToMarkdown` + `tiptapNodeToHtml`)
 
 When the operator switches the post format in the admin UI (e.g. `tiptap →
@@ -1206,7 +1249,7 @@ 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
+// packages/plugin-youtube/src/adapters.ts
 import type { TiptapNodeMarkdownAdapters, TiptapNodeHtmlAdapters } from 'ampless'
 
 export const tiptapNodeToMarkdown: TiptapNodeMarkdownAdapters = {
@@ -1244,7 +1287,10 @@ export const tiptapNodeToHtml: TiptapNodeHtmlAdapters = {
 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.
+fallback in the generated file is a no-op. As noted above, the exports
+`./editor` re-exports normally live in `./adapters.ts` — the codegen only
+cares that they're reachable from the `./editor` namespace, not where
+they're defined.
 
 #### `markdown → html` 2-hop
 

package/package.json

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