create-ampless 1.0.0-alpha.129 → 1.0.0-alpha.133

package/dist/index.js

@@ -1885,7 +1885,18 @@ var AMPLESS_MANAGED_APP_PATHS = [
   "app/login",
   "app/site"
 ];
-var AMPLESS_RETIRED_PATHS = [];
+var AMPLESS_RETIRED_PATHS = [
+  // Phase 7 preview pipeline migrated from a `'use server'` action to a
+  // Route Handler at `app/(admin)/admin/preview/route.tsx` (default
+  // endpoint: `/admin/preview`). The old action made Next.js 15+ refuse
+  // to compile the edit-post page
+  // because the import graph traced `react-dom/server` from Client
+  // Components through Server Action modules. Sites scaffolded before
+  // this change pick the new endpoint up on their next `update-ampless`
+  // — the new route file is seeded as part of the normal template
+  // sync, and the old action file is retired by this entry.
+  "app/(admin)/admin/_actions/render-preview.tsx"
+];
 var AMPLESS_PACKAGES = /* @__PURE__ */ new Set([
   "ampless",
   "@ampless/admin",
@@ -2145,6 +2156,80 @@ function detectIndent(jsonStr) {
   if (!m) return 2;
   return m[1].length;
 }
+function djb2Hash(s) {
+  let h = 5381;
+  for (let i = 0; i < s.length; i++) {
+    h = h * 33 ^ s.charCodeAt(i) | 0;
+  }
+  return (h >>> 0).toString(16);
+}
+async function regenerateEditorBootstrap(destDir, projectPkg) {
+  const targetPath = join3(destDir, "app", "(admin)", "admin", "_editor-bootstrap.tsx");
+  const installedPlugins = [];
+  const warnings = [];
+  const deps = projectPkg.dependencies ?? {};
+  for (const pkgName of Object.keys(deps)) {
+    const pkgJsonPath = join3(destDir, "node_modules", pkgName, "package.json");
+    if (!existsSync5(pkgJsonPath)) continue;
+    let mf;
+    try {
+      mf = JSON.parse(await readFile3(pkgJsonPath, "utf-8"));
+    } catch (e) {
+      warnings.push(`${pkgName}: failed to read package.json (${e instanceof Error ? e.message : String(e)}). Skipping editor wiring.`);
+      continue;
+    }
+    const ep = mf?.amplessPlugin?.editorExports;
+    if (typeof ep !== "string") continue;
+    if (!ep.startsWith("./") || ep.includes("..") || ep.startsWith("/") || /[?#]/.test(ep)) {
+      warnings.push(`${pkgName}: amplessPlugin.editorExports="${ep}" is invalid (must be a ./-prefixed relative subpath without .. or query/fragment). Skipping editor wiring.`);
+      continue;
+    }
+    if (!mf?.exports || typeof mf.exports[ep] === "undefined") {
+      warnings.push(`${pkgName}: amplessPlugin.editorExports="${ep}" is not declared in package.json#exports. Skipping editor wiring.`);
+      continue;
+    }
+    installedPlugins.push({ packageName: pkgName, editorExports: ep });
+  }
+  installedPlugins.sort((a, b) => a.packageName.localeCompare(b.packageName));
+  const lines = [];
+  lines.push("'use client'", "");
+  lines.push("// AUTO-GENERATED by `npm run update-ampless`. Do not edit \u2014 your changes");
+  lines.push("// will be overwritten on the next run. To enable / disable a plugin's");
+  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 } from '@ampless/admin/editor'");
+  const identifiers = [];
+  const seen = /* @__PURE__ */ new Map();
+  for (const p3 of installedPlugins) {
+    let ident = "__" + p3.packageName.replace(/^@/, "").replace(/[^a-zA-Z0-9]+/g, "_") + "_editor";
+    if (seen.has(ident) && seen.get(ident) !== p3.packageName) {
+      const suffix = djb2Hash(p3.packageName).slice(0, 8);
+      const orig = ident;
+      ident = `${ident}_${suffix}`;
+      warnings.push(`editor-bootstrap codegen: sanitised identifier "${orig}" collides between "${seen.get(orig)}" and "${p3.packageName}". Using "${ident}" for the latter to disambiguate.`);
+    }
+    seen.set(ident, p3.packageName);
+    const importSubpath = p3.editorExports.startsWith("./") ? `${p3.packageName}/${p3.editorExports.slice(2)}` : `${p3.packageName}/${p3.editorExports}`;
+    lines.push(`import { editorExtension as ${ident} } from '${importSubpath}'`);
+    identifiers.push(ident);
+  }
+  lines.push("");
+  lines.push("export function EditorBootstrap({ children }: { children: React.ReactNode }) {");
+  if (identifiers.length === 0) {
+    lines.push("  installAdminEditorExtensions([])");
+  } else {
+    lines.push("  installAdminEditorExtensions([");
+    for (const id of identifiers) lines.push(`    ${id},`);
+    lines.push("  ])");
+  }
+  lines.push("  return <>{children}</>");
+  lines.push("}");
+  lines.push("");
+  await mkdir2(dirname(targetPath), { recursive: true });
+  await writeFile3(targetPath, lines.join("\n"), "utf-8");
+  return { path: targetPath, pluginCount: installedPlugins.length, warnings };
+}
 async function runUpgradeIn(destDir, sharedDir, opts = {}) {
   const derivedRoot = opts.templatesRoot ?? join3(sharedDir, "..");
   const themeSyncEnabled = existsSync5(join3(derivedRoot, "_shared"));
@@ -2263,6 +2348,21 @@ async function runUpgradeIn(destDir, sharedDir, opts = {}) {
     const pm = usePnpm ? "pnpm" : "npm";
     await execa4(pm, ["install"], { cwd: destDir, stdio: "inherit" });
   }
+  const codegenProjectPkg = JSON.parse(
+    await readFile3(join3(destDir, "package.json"), "utf-8")
+  );
+  const bootstrapResult = await regenerateEditorBootstrap(destDir, codegenProjectPkg);
+  if (opts.noInstall) {
+    bootstrapResult.warnings.push(
+      "_editor-bootstrap.tsx was generated without running npm install \u2014 node_modules may be stale. Run `npm run update-ampless` (without --no-install) to pick up newly added plugin editor extensions."
+    );
+  }
+  for (const w of bootstrapResult.warnings) {
+    log3.warn(w);
+  }
+  log3.info(
+    `editor:  ${pc3.cyan(`auto-wired ${bootstrapResult.pluginCount} editor extension(s) in _editor-bootstrap.tsx`)}`
+  );
   return {
     added: replaceNew,
     updated: replaceUpdate,
@@ -2272,7 +2372,8 @@ async function runUpgradeIn(destDir, sharedDir, opts = {}) {
     themesPreserved: themeResult.preserved,
     themesQuarantined: themeResult.quarantined,
     packageJsonMerged: true,
-    obsoleteRemoved: obsoleteFiles
+    obsoleteRemoved: obsoleteFiles,
+    editorExtensionsWired: bootstrapResult.pluginCount
   };
 }
 async function runUpgrade(args) {

package/dist/templates/_shared/app/(admin)/admin/_editor-bootstrap.tsx

@@ -1,21 +1,13 @@
 'use client'
 
-// Phase 7 admin-editor extension slot. Templates wire first-party
-// embed plugins' tiptap Node extensions here so the admin's
-// <TiptapEditor> picks them up. Empty by default — uncomment the
-// imports + the registration to enable YouTube / x.com embeds.
-//
-// Wired into the admin layout via:
-//   createAdminLayout(admin, { editorBootstrap: EditorBootstrap })
+// Placeholder for fresh scaffolds before `update-ampless` runs.
+// `npm run update-ampless` rewrites this file with auto-wired plugin
+// editor extensions based on the project's installed `@ampless/plugin-*`
+// packages.
 
 import { installAdminEditorExtensions } from '@ampless/admin/editor'
-// import { youtubeEditor } from '@ampless/plugin-youtube/editor'
-// import { tweetEditor } from '@ampless/plugin-x-embed/editor'
 
 export function EditorBootstrap({ children }: { children: React.ReactNode }) {
-  installAdminEditorExtensions([
-    // youtubeEditor.extension,
-    // tweetEditor.extension,
-  ])
+  installAdminEditorExtensions([])
   return <>{children}</>
 }

package/dist/templates/_shared/app/(admin)/admin/posts/[postId]/page.tsx

@@ -1,5 +1,4 @@
 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)

package/dist/templates/_shared/app/(admin)/admin/posts/new/page.tsx

@@ -1,5 +1,4 @@
 import { admin } from '@/lib/admin'
 import { createNewPostPage } from '@ampless/admin/pages'
-import { renderPreviewHtml } from '../../_actions/render-preview'
 
-export default createNewPostPage(admin, { renderPreviewAction: renderPreviewHtml })
+export default createNewPostPage(admin)

package/dist/templates/_shared/app/(admin)/admin/preview/route.tsx

@@ -0,0 +1,66 @@
+import type { Post } from 'ampless'
+import { admin } from '@/lib/admin'
+
+/**
+ * Preview-only Route Handler. Client-side `<PostForm>` / `<PostHistoryPanel>`
+ * POST a draft Post to this endpoint while the preview tab is open; we
+ * render the body + page-level scripts via `ampless.renderBody` /
+ * `publicPostScriptsForPage` and return a fully-rendered HTML string
+ * that the admin shows in an iframe (`sandbox="allow-scripts"`).
+ *
+ * Why a Route Handler instead of a Server Action: Next.js 15+
+ * refuses to compile Client Components that reach `react-dom/server`
+ * through a `'use server'` module, because the build traces the
+ * import graph from Client Components through Server Action modules.
+ * Putting this rendering behind a Route Handler decouples it from
+ * that graph entirely — the form fetches a plain HTTP endpoint and
+ * the bundler never walks from `<PostForm>` into here. The endpoint
+ * also gets an explicit `admin.isEditor()` gate so a future change
+ * to the `(admin)` route-group middleware can't silently turn
+ * preview into a content-leak vector for unpublished drafts.
+ *
+ * The `react-dom/server` import itself is loaded via dynamic
+ * `import()` inside the handler. Next.js 16's Turbopack flags any
+ * top-level static `import 'react-dom/server'` reached from the app
+ * router build (Route Handlers included), so we deliberately defer
+ * the resolution to request time — the module is still pulled from
+ * the same Node.js subpath that `next start` ships, just not visible
+ * to the build-time import-graph walker.
+ *
+ * Auth: locked to authenticated editors. Anonymous + reader access is
+ * 403. This matches the rest of `/admin/**`, which is gated by the
+ * `(admin)` route group + middleware, but we add an explicit check
+ * here as defence-in-depth against the middleware gate being
+ * misconfigured.
+ */
+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()
+  // IMPORTANT: include BOTH the body and the page-level scripts so
+  // widgets like x.com's `widgets.js` get a chance to hydrate in the
+  // iframe.
+  const node = (
+    <>
+      {await ampless.renderBody(draft)}
+      {await ampless.publicPostScriptsForPage([draft])}
+    </>
+  )
+  // Dynamic import: see top-of-file comment. The module is server-only
+  // and resolved at request time.
+  const { renderToStaticMarkup } = await import('react-dom/server')
+  return new Response(renderToStaticMarkup(node), {
+    headers: {
+      'Content-Type': 'text/html; charset=utf-8',
+      'Cache-Control': 'no-store',
+    },
+  })
+}

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

@@ -777,25 +777,67 @@ runtime は `src` のホスト allowlist を強制しない。CSP はサイト
 
 ## 6d. Admin エディタ拡張の配線 (Phase 7)
 
-admin エディタに tiptap Node 拡張を提供するプラグインは、別途 `./editor` subpath の client-side エントリを出荷する。テンプレート側で `_editor-bootstrap.tsx` から配線する:
+admin エディタに tiptap Node 拡張を提供するプラグインは、別途 `./editor` subpath の client-side エントリを出荷する。
+`app/(admin)/admin/_editor-bootstrap.tsx` は `npm run update-ampless` によって**自動生成**される — 手動で編集してはならない。
+
+### プラグイン著者向け
+
+`package.json#amplessPlugin` に `editorExports` を宣言する:
+
+```jsonc
+// packages/plugin-youtube/package.json
+"amplessPlugin": {
+  "apiVersion": 1,
+  "name": "youtube",
+  "trustLevel": "trusted",
+  "capabilities": ["contentFields"],
+  "editorExports": "./editor"   // ← editor module のある subpath
+}
+```
+
+その subpath から `editorExtension` を named export する:
+
+```ts
+// packages/plugin-youtube/src/editor.tsx
+export const editorExtension = AmplessYoutubeNode   // tiptap Node または Extension
+```
+
+`package.json#exports` にも同 subpath を宣言すること（codegen がこれを検証する — 未宣言の場合は warning を出してそのプラグインをスキップする）:
+
+```jsonc
+"exports": {
+  ".":       { "import": "./dist/index.js", "types": "./dist/index.d.ts" },
+  "./editor": { "import": "./dist/editor.js", "types": "./dist/editor.d.ts" }
+}
+```
+
+### プラグインユーザー（サイトエンジニア）向け
+
+1. `npm i @ampless/plugin-youtube@alpha` — plugin を dependency として追加する。
+2. `cms.config.ts` に登録してサーバーサイド renderer を有効化する。
+3. `npm run update-ampless` — インストール済み plugin の manifest から `_editor-bootstrap.tsx` を自動再生成する。
+
+生成されたファイルはリポジトリにコミットされ、以下のような内容になる:
 
 ```tsx
-// templates/_shared/app/(admin)/admin/_editor-bootstrap.tsx
+// app/(admin)/admin/_editor-bootstrap.tsx  (AUTO-GENERATED — 編集不可)
 'use client'
+// AUTO-GENERATED by `npm run update-ampless`. Do not edit — your changes
+// will be overwritten on the next run.
 import { installAdminEditorExtensions } from '@ampless/admin/editor'
-import { youtubeEditor } from '@ampless/plugin-youtube/editor'
-import { tweetEditor } from '@ampless/plugin-x-embed/editor'
+import { editorExtension as __ampless_plugin_x_embed_editor } from '@ampless/plugin-x-embed/editor'
+import { editorExtension as __ampless_plugin_youtube_editor } from '@ampless/plugin-youtube/editor'
 
 export function EditorBootstrap({ children }: { children: React.ReactNode }) {
   installAdminEditorExtensions([
-    youtubeEditor.extension,
-    tweetEditor.extension,
+    __ampless_plugin_x_embed_editor,
+    __ampless_plugin_youtube_editor,
   ])
   return <>{children}</>
 }
 ```
 
-その上で layout に渡す:
+このファイルは admin layout に渡される（テンプレートに既に組み込まれているので追加の作業は不要）:
 
 ```tsx
 // templates/_shared/app/(admin)/admin/layout.tsx
@@ -806,18 +848,33 @@ export default createAdminLayout(admin, { editorBootstrap: EditorBootstrap })
 
 `installAdminEditorExtensions` は idempotent で、render 時に client component 内で呼ばれる。admin の `<TiptapEditor>` は毎回 render 時に登録済みリストを built-in extensions の末尾に spread する。
 
+### active source と完全無効化
+
+**エディタ配線の active source は `package.json#dependencies`**（= `node_modules`）であり、`cms.config.ts` ではない。
+
+- plugin を `cms.config.ts` から外しても `package.json` に dep が残っていれば、editor の paste rule は**有効のまま**になる。editor は tiptap document にそのノード型を挿入できるが、公開 renderer はレンダリングしない（不整合状態 — 避けること）。
+- 完全に無効化するには: `cms.config.ts` から削除 **かつ** `npm uninstall @ampless/plugin-...` を実行し、`npm run update-ampless` で bootstrap ファイルを再生成する。
+
 ### エディタプレビューのパイプライン
 
-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 +882,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/dist/templates/_shared/docs/plugin-author-guide.md

@@ -1026,26 +1026,72 @@ middleware. This is documented in each plugin's README.
 ## 6d. Admin editor extension wiring (Phase 7)
 
 Plugins that contribute tiptap Node extensions to the admin editor
-ship a separate client-side entry under the `./editor` subpath. The
-template wires it up in `_editor-bootstrap.tsx`:
+ship a separate client-side entry under the `./editor` subpath.
+`app/(admin)/admin/_editor-bootstrap.tsx` is **auto-generated** by
+`npm run update-ampless` — you should not edit it by hand.
+
+### For plugin authors
+
+Declare `editorExports` in `package.json#amplessPlugin`:
+
+```jsonc
+// packages/plugin-youtube/package.json
+"amplessPlugin": {
+  "apiVersion": 1,
+  "name": "youtube",
+  "trustLevel": "trusted",
+  "capabilities": ["contentFields"],
+  "editorExports": "./editor"   // ← subpath where the editor module lives
+}
+```
+
+Export `editorExtension` as a named symbol from that subpath:
+
+```ts
+// packages/plugin-youtube/src/editor.tsx
+export const editorExtension = AmplessYoutubeNode   // tiptap Node or Extension
+```
+
+The subpath must be declared in `package.json#exports` as well (the
+codegen validates this — a missing `exports` entry triggers a warning
+and the plugin is skipped):
+
+```jsonc
+"exports": {
+  ".":       { "import": "./dist/index.js", "types": "./dist/index.d.ts" },
+  "./editor": { "import": "./dist/editor.js", "types": "./dist/editor.d.ts" }
+}
+```
+
+### For plugin users (site engineers)
+
+1. `npm i @ampless/plugin-youtube@alpha` — add the plugin as a dependency.
+2. Register it in `cms.config.ts` for the server-side renderer.
+3. `npm run update-ampless` — regenerates `_editor-bootstrap.tsx`
+   automatically from the installed plugin manifests.
+
+The generated file is committed to your repo and looks like:
 
 ```tsx
-// templates/_shared/app/(admin)/admin/_editor-bootstrap.tsx
+// app/(admin)/admin/_editor-bootstrap.tsx  (AUTO-GENERATED — do not edit)
 'use client'
+// AUTO-GENERATED by `npm run update-ampless`. Do not edit — your changes
+// will be overwritten on the next run.
 import { installAdminEditorExtensions } from '@ampless/admin/editor'
-import { youtubeEditor } from '@ampless/plugin-youtube/editor'
-import { tweetEditor } from '@ampless/plugin-x-embed/editor'
+import { editorExtension as __ampless_plugin_x_embed_editor } from '@ampless/plugin-x-embed/editor'
+import { editorExtension as __ampless_plugin_youtube_editor } from '@ampless/plugin-youtube/editor'
 
 export function EditorBootstrap({ children }: { children: React.ReactNode }) {
   installAdminEditorExtensions([
-    youtubeEditor.extension,
-    tweetEditor.extension,
+    __ampless_plugin_x_embed_editor,
+    __ampless_plugin_youtube_editor,
   ])
   return <>{children}</>
 }
 ```
 
-Then thread it into the layout:
+The file is then wired into the admin layout (already in the template — no
+extra work required):
 
 ```tsx
 // templates/_shared/app/(admin)/admin/layout.tsx
@@ -1058,20 +1104,42 @@ 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.
 
+### Active source and full disable
+
+**The active source for editor wiring is `package.json#dependencies`**
+(= `node_modules`), not `cms.config.ts`. This means:
+
+- Removing a plugin from `cms.config.ts` but keeping it in
+  `package.json` leaves the editor paste rule active. The editor can
+  still insert the node type into the tiptap document, but the public
+  renderer won't render it (inconsistent state — avoid).
+- To fully disable a plugin's editor extension: remove it from
+  `cms.config.ts` **and** run `npm uninstall @ampless/plugin-...`,
+  then `npm run update-ampless` to regenerate the bootstrap file.
+
 ### Editor preview pipeline
 
 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 +1147,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/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.26",
-    "@ampless/plugin-cookie-consent": "^0.1.0-alpha.17",
-    "@ampless/plugin-gtm": "^0.2.0-alpha.25",
-    "@ampless/plugin-og-image": "^0.2.0-alpha.42",
-    "@ampless/plugin-plausible": "^0.2.0-alpha.25",
-    "@ampless/plugin-reading-time": "^0.1.0-alpha.15",
-    "@ampless/plugin-rss": "^0.2.0-alpha.42",
-    "@ampless/plugin-schema-jsonld": "^0.1.1-alpha.21",
-    "@ampless/plugin-seo": "^0.2.0-alpha.42",
-    "@ampless/plugin-webhook": "^0.2.0-alpha.43",
-    "@ampless/admin": "^1.0.0-alpha.75",
-    "@ampless/backend": "^1.0.0-alpha.64",
-    "@ampless/runtime": "^1.0.0-alpha.51",
+    "@ampless/plugin-analytics-ga4": "^0.2.0-alpha.28",
+    "@ampless/plugin-cookie-consent": "^0.1.0-alpha.19",
+    "@ampless/plugin-gtm": "^0.2.0-alpha.27",
+    "@ampless/plugin-og-image": "^0.2.0-alpha.44",
+    "@ampless/plugin-plausible": "^0.2.0-alpha.27",
+    "@ampless/plugin-reading-time": "^0.1.0-alpha.17",
+    "@ampless/plugin-rss": "^0.2.0-alpha.44",
+    "@ampless/plugin-schema-jsonld": "^0.1.1-alpha.23",
+    "@ampless/plugin-seo": "^0.2.0-alpha.44",
+    "@ampless/plugin-webhook": "^0.2.0-alpha.45",
+    "@ampless/admin": "^1.0.0-alpha.77",
+    "@ampless/backend": "^1.0.0-alpha.66",
+    "@ampless/runtime": "^1.0.0-alpha.53",
     "@digital-go-jp/tailwind-theme-plugin": "^0.3.4",
-    "ampless": "^1.0.0-alpha.42",
+    "ampless": "^1.0.0-alpha.44",
     "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.129",
+  "version": "1.0.0-alpha.133",
   "description": "Create a new ampless project",
   "license": "MIT",
   "type": "module",

package/dist/templates/_shared/app/(admin)/admin/_actions/render-preview.tsx

@@ -1,32 +0,0 @@
-'use server'
-
-// Phase 7 preview pipeline. <PostForm> / <PostHistoryPanel> calls this
-// server action with the in-flight draft Post; we render the body +
-// page-level scripts on the server (where async ReactNode +
-// `contentFields` plugin renderers can run) and return a complete HTML
-// string that the admin shows in an iframe (sandbox=`allow-scripts`).
-//
-// Server-side is the only place this can live: `ampless.renderBody`
-// returns a Promise<ReactNode>, so client code can't call it inline.
-// The action also has access to the `Ampless` instance via
-// `admin.getAmpless()` which the client never sees.
-
-import { renderToStaticMarkup } from 'react-dom/server'
-import type { Post } from 'ampless'
-import { admin } from '@/lib/admin'
-
-export async function renderPreviewHtml(draft: Post): Promise<string> {
-  const ampless = await admin.getAmpless()
-  // IMPORTANT: include BOTH the body and the page-level scripts so
-  // widgets like x.com's `widgets.js` get a chance to hydrate in the
-  // iframe. Without `publicPostScriptsForPage([draft])` the embed
-  // blockquote would render but never load the widget JS, and authors
-  // wouldn't see what the public page actually looks like.
-  const node = (
-    <>
-      {await ampless.renderBody(draft)}
-      {await ampless.publicPostScriptsForPage([draft])}
-    </>
-  )
-  return renderToStaticMarkup(node)
-}