ampless 1.0.0-alpha.42 → 1.0.0-alpha.43

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

@@ -808,16 +808,24 @@ export default createAdminLayout(admin, { editorBootstrap: EditorBootstrap })
 
 ### エディタプレビューのパイプライン
 
-admin の edit / new post フォームは preview ペインを `<iframe sandbox="allow-scripts">` で表示する。`srcDoc` はテンプレート側 server action が返す HTML:
+admin の edit / new post フォームは preview ペインを `<iframe sandbox="allow-scripts">` で表示する。`srcDoc` はテンプレート側 preview Route Handler が返す HTML。テンプレート scaffold は handler を `app/(admin)/admin/preview/route.tsx` に同梱する:
 
 ```tsx
-// templates/_shared/app/(admin)/admin/_actions/render-preview.tsx
-'use server'
-import { renderToStaticMarkup } from 'react-dom/server'
+// templates/_shared/app/(admin)/admin/preview/route.tsx
 import type { Post } from 'ampless'
 import { admin } from '@/lib/admin'
 
-export async function renderPreviewHtml(draft: Post): Promise<string> {
+export async function POST(req: Request): Promise<Response> {
+  const session = await admin.getServerSession()
+  if (!admin.isEditor(session)) {
+    return new Response('Forbidden', { status: 403 })
+  }
+  let draft: Post
+  try {
+    draft = (await req.json()) as Post
+  } catch {
+    return new Response('Bad Request', { status: 400 })
+  }
   const ampless = await admin.getAmpless()
   const node = (
     <>
@@ -825,21 +833,35 @@ export async function renderPreviewHtml(draft: Post): Promise<string> {
       {await ampless.publicPostScriptsForPage([draft])}
     </>
   )
-  return renderToStaticMarkup(node)
+  // dynamic import: 下の「Server Action ではなく Route Handler を採用した理由」参照。
+  const { renderToStaticMarkup } = await import('react-dom/server')
+  return new Response(renderToStaticMarkup(node), {
+    headers: {
+      'Content-Type': 'text/html; charset=utf-8',
+      'Cache-Control': 'no-store',
+    },
+  })
 }
 ```
 
-page factory は `renderPreviewAction` オプションでこの action を thread する:
+`<PostForm>` / `<PostHistoryPanel>` は素のままで `/admin/preview` に draft を POST する — call site で追加の wiring は不要:
 
 ```tsx
 // templates/_shared/app/(admin)/admin/posts/[postId]/page.tsx
 import { admin } from '@/lib/admin'
 import { createEditPostPage } from '@ampless/admin/pages'
-import { renderPreviewHtml } from '../../_actions/render-preview'
 
-export default createEditPostPage(admin, { renderPreviewAction: renderPreviewHtml })
+export default createEditPostPage(admin)
 ```
 
+admin が非デフォルトパス（Next.js `basePath` やカスタム prefix）にマウントされている場合は、page factory の `previewEndpoint` option で endpoint を上書きできる:
+
+```tsx
+export default createEditPostPage(admin, { previewEndpoint: '/cms/admin/preview' })
+```
+
+Server Action ではなく Route Handler を採用した理由: `'use server'` モジュール内部で `react-dom/server` 由来の rendering を行うと、Next.js 15+ が edit-post page の compile に失敗する。build 時に Client Component から Server Action モジュール経由で import graph を辿るため、その経路上で `react-dom/server` に到達した時点で「You're importing a component that imports react-dom/server」チェックが発火する。Route Handler に切り出すことで rendering を import graph から完全に切り離せる — `<PostForm>` は plain な HTTP endpoint を fetch するだけで、bundler は form から handler 側へ踏み込まない。さらに handler 自身が `admin.isEditor()` を明示的にチェックすることで、将来 `(admin)` route-group gate が誤設定された場合の安全側のフェールセーフになる。`react-dom/server` の import 自体を dynamic にしているのは Next.js 16 の Turbopack が、Route Handler を含む app router build 経路で reach できる top-level の `react-dom/server` static import を一律で flag するため。request 時に解決することで build-time import-graph walker から外しつつ、runtime では同じ Node.js subpath からロードする。
+
 iframe の `sandbox="allow-scripts"` は `allow-same-origin` を含まないので、preview の中身は opaque origin で動作する → widget script は admin の DOM に触れない。トレードオフ: widget が自身の origin の storage にアクセスできない場合に正しく動かない可能性がある。Phase 7 時点の dogfood では YouTube iframe / x.com widgets.js とも opaque origin で動作することを確認済み。将来 non-opaque origin が必要な widget が出てきた場合、escape hatch は別 subdomain の preview route + 適切な CSP — sandbox flag を緩めるのは取らない。
 
 ---

package/docs/plugin-author-guide.md

@@ -1062,16 +1062,25 @@ registered list onto its built-in extensions on every render.
 
 The admin's edit / new post forms render the preview pane in an
 `<iframe sandbox="allow-scripts">` whose `srcDoc` is the HTML returned
-by the template's server action:
+by the template's preview Route Handler. The template scaffold ships
+the handler at `app/(admin)/admin/preview/route.tsx`:
 
 ```tsx
-// templates/_shared/app/(admin)/admin/_actions/render-preview.tsx
-'use server'
-import { renderToStaticMarkup } from 'react-dom/server'
+// templates/_shared/app/(admin)/admin/preview/route.tsx
 import type { Post } from 'ampless'
 import { admin } from '@/lib/admin'
 
-export async function renderPreviewHtml(draft: Post): Promise<string> {
+export async function POST(req: Request): Promise<Response> {
+  const session = await admin.getServerSession()
+  if (!admin.isEditor(session)) {
+    return new Response('Forbidden', { status: 403 })
+  }
+  let draft: Post
+  try {
+    draft = (await req.json()) as Post
+  } catch {
+    return new Response('Bad Request', { status: 400 })
+  }
   const ampless = await admin.getAmpless()
   const node = (
     <>
@@ -1079,22 +1088,54 @@ export async function renderPreviewHtml(draft: Post): Promise<string> {
       {await ampless.publicPostScriptsForPage([draft])}
     </>
   )
-  return renderToStaticMarkup(node)
+  // Dynamic import: see "Why a Route Handler" below.
+  const { renderToStaticMarkup } = await import('react-dom/server')
+  return new Response(renderToStaticMarkup(node), {
+    headers: {
+      'Content-Type': 'text/html; charset=utf-8',
+      'Cache-Control': 'no-store',
+    },
+  })
 }
 ```
 
-Page factories thread the action down via the `renderPreviewAction`
-option:
+`<PostForm>` / `<PostHistoryPanel>` POST the draft to `/admin/preview`
+out of the box — no extra wiring at the call site:
 
 ```tsx
 // templates/_shared/app/(admin)/admin/posts/[postId]/page.tsx
 import { admin } from '@/lib/admin'
 import { createEditPostPage } from '@ampless/admin/pages'
-import { renderPreviewHtml } from '../../_actions/render-preview'
 
-export default createEditPostPage(admin, { renderPreviewAction: renderPreviewHtml })
+export default createEditPostPage(admin)
 ```
 
+If the admin is mounted at a non-default path (Next.js `basePath` or
+a custom prefix), override the endpoint via the page factory's
+`previewEndpoint` option:
+
+```tsx
+export default createEditPostPage(admin, { previewEndpoint: '/cms/admin/preview' })
+```
+
+Why a Route Handler rather than a Server Action: putting
+`react-dom/server`-driven rendering inside a `'use server'` module
+makes Next.js 15+ refuse to compile the edit-post page, because the
+build traces the import graph from Client Components through Server
+Action modules and any reach to `react-dom/server` along that path
+trips the "You're importing a component that imports
+react-dom/server" check. A Route Handler decouples the rendering
+from that graph entirely — `<PostForm>` fetches a plain HTTP
+endpoint and the bundler never walks from the form into here. The
+handler's explicit `admin.isEditor()` check also defends against
+accidental exposure if the `(admin)` route-group gate is ever
+misconfigured. The `react-dom/server` import itself is dynamic
+because Next.js 16's Turbopack flags any top-level static import of
+`react-dom/server` reached from the app router build, Route Handlers
+included; deferring it to request time keeps the module outside the
+build-time import-graph walker while still loading it from the same
+Node.js subpath at runtime.
+
 The iframe's `sandbox="allow-scripts"` (without `allow-same-origin`)
 keeps preview content in an opaque origin so widget scripts cannot
 reach the admin's DOM. The trade-off is that some widgets may misbehave

package/package.json

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