npm - create-ampless - Versions diffs - 1.0.0-alpha.61 → 1.0.0-alpha.63 - Mend

create-ampless 1.0.0-alpha.61 → 1.0.0-alpha.63

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (7) hide show

package/dist/index.js +2 -1
package/dist/templates/_shared/app/(admin)/admin/plugins/page.tsx +5 -0
package/dist/templates/_shared/app/layout.tsx +23 -1
package/dist/templates/_shared/docs/plugin-author-guide.ja.md +500 -0
package/dist/templates/_shared/docs/plugin-author-guide.md +630 -0
package/dist/templates/_shared/package.json +8 -8
package/package.json +1 -1

package/dist/index.js CHANGED Viewed

@@ -1756,7 +1756,8 @@ var AMPLESS_PACKAGES = /* @__PURE__ */ new Set([
   "@ampless/plugin-seo",
   "@ampless/plugin-rss",
   "@ampless/plugin-webhook",
-  "@ampless/plugin-og-image"
+  "@ampless/plugin-og-image",
+  "@ampless/plugin-analytics-ga4"
 ]);
 var AMPLESS_MANAGED_SCRIPTS = /* @__PURE__ */ new Set([
   "sandbox",

package/dist/templates/_shared/app/(admin)/admin/plugins/page.tsx ADDED Viewed

@@ -0,0 +1,5 @@
+import { admin } from '@/lib/admin'
+import { createPluginsPage } from '@ampless/admin/pages'
+export const dynamic = 'force-dynamic'
+export default createPluginsPage(admin)

package/dist/templates/_shared/app/layout.tsx CHANGED Viewed

@@ -14,7 +14,15 @@ export async function generateMetadata(): Promise<Metadata> {
 export default async function RootLayout({ children }: { children: React.ReactNode }) {
   const h = await headers()
-  const theme = await ampless.loadThemeConfig()
+  // Resolve theme, plugin head + body in parallel. `publicHead` and
+  // `publicBodyEnd` both fetch the S3 site-settings cache to bind
+  // `ctx.setting()`; Next.js fetch dedupe collapses that into a
+  // single round trip when the two run on the same request.
+  const [theme, pluginHead, pluginBodyEnd] = await Promise.all([
+    ampless.loadThemeConfig(),
+    ampless.publicHead(),
+    ampless.publicBodyEnd(),
+  ])
   const themeCss = renderThemeCss(theme.cssVars)
   const locale = admin.locale
   const dict = getDictionary(locale)
@@ -45,6 +53,15 @@ export default async function RootLayout({ children }: { children: React.ReactNo
             against the static defaults. Validated values only — see
             ampless `validateThemeValue`. */}
         {themeCss && <style dangerouslySetInnerHTML={{ __html: themeCss }} />}
+        {/* Descriptor-based plugin head injection (Phase 1+2). Each
+            active plugin's `publicHead()` runs validation here; the
+            output is a `<Fragment>` of `<script>` / `<meta>` / `<link>`
+            / `<noscript>` elements. Placed after the theme style so
+            plugin-emitted overrides win on the rare collision.
+            Awaited via Promise.all above so admin-managed
+            `settings.public` values flow into ctx.setting() before
+            render. */}
+        {pluginHead}
       </head>
       {/* `data-theme` selects which theme's `tokens.css` block matches.
           The active theme is resolved from `theme.active` site setting,
@@ -55,6 +72,11 @@ export default async function RootLayout({ children }: { children: React.ReactNo
             {children}
           </I18nProvider>
         </Providers>
+        {/* Descriptor-based body-end injection (Phase 1+2). GTM
+            no-script iframe / chat widgets / analytics tail snippets
+            land here. Awaited above so the same ctx.setting()
+            snapshot powers both head + body. */}
+        {pluginBodyEnd}
       </body>
     </html>
   )

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

@@ -0,0 +1,500 @@
+<!--
+  Source of truth lives in packages/ampless/docs/plugin-author-guide.md.
+  Keep both copies in sync — the scaffold copy at
+  templates/_shared/docs/plugin-author-guide.ja.md must mirror this file
+  byte-for-byte until we add a CI check.
+-->
+> English: [plugin-author-guide.md](./plugin-author-guide.md)
+# ampless プラグインの書き方
+このガイドは、初めての `definePlugin()` 呼び出しから admin 編集可能な設定パネル、そして npm 公開に至るまで、ampless プラグインを ship するために必要な手順を一通りカバーします。Phase 1 + Phase 2 の機能を網羅 — descriptor ベースの `<head>` / `<body>` 注入、非同期イベントフック、admin 管理の `settings.public` 値です。
+設計の経緯と背景は [`docs/architecture/08-plugin-architecture.md`](https://github.com/heavymoons/ampless/blob/main/docs/architecture/08-plugin-architecture.md) に集約。本ページはその実装ハンドブック側です。
+---
+## 1. プラグインで何ができるか
+ampless プラグインは `AmplessPlugin` オブジェクトを返す TypeScript モジュールです。以下のうち 1 つ以上のサーフェスにフックします:
+| サーフェス | 実行場所 | 同期 / 非同期 | Phase |
+|---|---|---|---|
+| `metadata(post, site)` | 投稿の `generateMetadata()` | 同期 | 既存 |
+| `siteMetadata(site)` | root layout の `generateMetadata()` | 同期 | 既存 |
+| `publicHead(ctx)` | root layout の `<head>` | 同期 (async layout から呼ばれる) | 1 |
+| `publicBodyEnd(ctx)` | root layout の `<body>` 末尾 | 同期 | 1 |
+| `ogImage` | `/og/[slug]` ルート | リクエスト時、公開 Lambda 内 | 既存 |
+| `hooks` | trust_level に応じた processor Lambda | 非同期、SQS イベントで起動 | 既存 |
+| `settings.public` | `/admin/plugins` フォーム | 宣言的なマニフェスト | 2 |
+**現時点でできないこと** (将来の privileged 層実装に依存、ロードマップ参照):
+- 任意の `ReactNode` をページに注入 — descriptor 変種のみ許可
+- 公開 Next.js プロセス内で TCP ソケットを開く。trusted Lambda も外向き HTTP のみ
+- admin ルート / server ルート / コンテンツフィールドの追加 — Phase 6b 予約
+- secret の読み書き。`secretSettings` capability は Phase 6a 予約
+---
+## 2. 最小ファイル構成
+プラグインは小さな npm パッケージとして公開しても、サイトのモノレポ内に置いてもよいです。on-disk の構成はどちらでも同じ:
+```
+my-plugin/
+  package.json
+  tsconfig.json
+  tsup.config.ts
+  src/
+    index.ts
+    index.test.ts
+```
+本レポ内の `packages/plugin-rss/` と `packages/plugin-analytics-ga4/` が動作する参考実装です。
+最小の `src/index.ts`:
+```ts
+import { definePlugin, type AmplessPlugin } from 'ampless'
+export default function myPlugin(): AmplessPlugin {
+  return definePlugin({
+    name: 'my-plugin',
+    apiVersion: 1,
+    trust_level: 'untrusted',
+    capabilities: ['publicHead'],
+    publicHead() {
+      return [{ type: 'meta', name: 'x-plugin', content: 'hi' }]
+    },
+  })
+}
+```
+`cms.config.ts` に差し込み:
+```ts
+import myPlugin from 'my-plugin'
+export default defineConfig({
+  site: { name: 'My Blog', url: 'https://example.com' },
+  plugins: [myPlugin()],
+})
+```
+これで完了。`npm run dev` を再起動して任意のページのソースを表示すると `<meta name="x-plugin" content="hi" />` が `<head>` に出ています。
+---
+## 3. `AmplessPlugin` マニフェスト
+```ts
+interface AmplessPlugin {
+  name: string                      // パッケージ風の識別子。例: 'analytics-ga4'
+  apiVersion: 1                     // 契約が変わるときだけ bump
+  trust_level: 'untrusted' | 'trusted' | 'privileged'
+  instanceId?: string               // 複数インストール時の namespace
+  displayName?: LocalizedString     // admin UI ラベル
+  capabilities?: readonly PluginCapability[]
+  hooks?: { ... }                   // 非同期イベント
+  metadata?(post, site): PluginMetadata
+  siteMetadata?(site): PluginMetadata
+  publicHead?(ctx): readonly PublicHeadDescriptor[]
+  publicBodyEnd?(ctx): readonly PublicBodyDescriptor[]
+  ogImage?: OgImageConfig
+  settings?: { public?: readonly PluginSettingField[] }
+}
+```
+### `name`
+短い識別子 (`'analytics-ga4'`、`'rss'`、`'webhook'` など)。デフォルトの `instanceId` および trusted processor が S3 に書き出す `public/plugins/<name>/` のプレフィックスに使われます。`/^[a-zA-Z0-9_-]+$/` 必須 — 「命名規則」セクション参照。
+### `apiVersion: 1`
+今日は 1 のみ。将来の互換性破壊バージョンが出たらこの数字が bump され、runtime は未知の値を黙って bind せず拒否します。
+### `instanceId`
+optional、デフォルトは `name`。同じプラグインを 1 サイトで複数 instance 動かせる作り (例: 2 つの GA4 measurement ID、チャットプラットフォーム毎の webhook) では、ホストに `instanceId` を指定させて各々独立した namespace を持たせる:
+```ts
+analyticsGa4Plugin({ instanceId: 'marketing' })
+analyticsGa4Plugin({ instanceId: 'product' })
+```
+`instanceId` も `name` も `/^[a-zA-Z0-9_-]+$/` を満たす必要があります。`.` は `pk='siteconfig', sk='plugins.<id>.<key>'` の区切りを壊します。scope (`@foo/bar`) やスラッシュは予約済みです。
+### `displayName`
+`/admin/plugins` のパネル見出し。単一ロケールのプラグインなら平文の文字列で十分。`{ en: 'GA4', ja: 'GA4' }` 形式の per-locale map にすると admin のアクティブロケールに応じて読み分けられます。
+---
+## 4. `trust_level` の選び方
+3 階層、選択基準は **イベントフック (hooks) が何を必要とするか** で決まります (sync サーフェスは IAM に触れない):
+| 階層 | IAM | 用途 |
+|---|---|---|
+| `untrusted` | なし (SQS consume のみ) | head/body descriptor、webhook 配送、コンテンツ変換 |
+| `trusted` | 投稿読み出し、`public/plugins/<name>/...` への書き込み | RSS フィード、sitemap、計算済み JSON インデックス |
+| `privileged` | 予約 | 将来: SES、secret、private S3 |
+決め方の目安:
+- **`publicHead` / `publicBodyEnd` / `metadata` だけ必要** → `untrusted`
+- **hooks から投稿を読みたい (publish 時にフィードを再生成等)** → `trusted`
+- **`public/plugins/*` 以外への S3 PutObject や他の AWS API が必要** → 今はプラグインで ship せず、privileged 層を待つかプラグイン外で実装
+trust level がズレているプラグインは「権限不足で sliently fail」または「不要に強い権限を持つ」のどちらか。階層を切り替えて再デプロイすれば直ります。
+---
+## 5. 同期サーフェス
+**公開 Next.js プロセス** (サイト訪問者のリクエストスレッド) 内で実行されます。AWS に対しては純 (IAM・ネットワーク無し) で、同期実行です。
+| サーフェス | 戻り値 | 用途 |
+|---|---|---|
+| `metadata(post, site)` | `PluginMetadata` (Next.js `Metadata` 形) | 投稿単位の `<title>` / OGP / Twitter / canonical |
+| `siteMetadata(site)` | `PluginMetadata` | サイト全体の `<title>` / favicon / RSS `<link rel="alternate">` |
+| `publicHead(ctx)` | `PublicHeadDescriptor[]` | 解析ローダー、フォント、jsonld、hreflang |
+| `publicBodyEnd(ctx)` | `PublicBodyDescriptor[]` | GTM no-script フレーム、チャットウィジェット、末尾スニペット |
+`ctx` オブジェクトの中身:
+```ts
+{
+  site: Config['site']      // name / url / description
+  setting<T>(key: string): T | undefined
+}
+```
+`ctx.setting()` は Phase 2 で追加された admin 管理値アクセッサ — §8 参照。
+---
+## 6. Descriptor リファレンス
+`publicHead` と `publicBodyEnd` は **descriptor オブジェクト** を返します。`ReactNode` ではありません。runtime が validation してから React 要素を組み立てます。これが untrusted コードを公開描画パスで動かすための安全境界です。
+### 共通の variant
+```ts
+// 外部 script
+{
+  type: 'script',
+  id: 'ga4-loader-analytics-ga4',
+  src: 'https://www.googletagmanager.com/gtag/js?id=G-XXX',
+  strategy: 'afterInteractive', // または 'lazyOnload'
+  async: true,                  // optional; strategy が暗黙的に付ける
+  defer: false,
+  attrs: { crossorigin: 'anonymous' },
+}
+// inline script — id は必須 (重複検知に使う)
+{
+  type: 'inlineScript',
+  id: 'ga4-init-analytics-ga4',
+  body: "/* 一行ブートストラップ */",
+  strategy: 'afterInteractive',
+}
+// Meta / link / noscript
+{ type: 'meta', name: 'theme-color', content: '#fff' }
+{ type: 'meta', property: 'og:image', content: 'https://…' }
+{ type: 'link', rel: 'preconnect', href: 'https://cdn.example.com' }
+{ type: 'noscript', id: 'gtm-fallback-msg', html: '<p>JS required</p>' }
+```
+### body 専用の variant
+```ts
+// iframe — GTM の no-script フォールバック、チャットウィジェット等
+{
+  type: 'iframe',
+  id: 'gtm-fallback',
+  src: 'https://www.googletagmanager.com/ns.html?id=GTM-XYZ',
+  height: 0,
+  width: 0,
+  attrs: { sandbox: 'allow-scripts' },
+}
+```
+### Validation ルール
+- **URL scheme allowlist**: `http`、`https`、または相対パス。`javascript:`、`data:`、`vbscript:`、`blob:`、`file:` は要素描画前に拒否されます
+- **`attrs` allowlist**: `data-*`、`crossorigin`、`referrerpolicy`、`integrity`、`fetchpriority`、`loading`、`sandbox`、`allow`、`allowfullscreen`。それ以外は dev warn 付きで drop
+- **`inlineScript.id` は必須**。無いとプラグイン同士が似たスニペットを emit したときに dedup できず、dev warning も index 番号を指すだけで原因プラグインを特定できません
+- **id 重複**: 最後の出現が勝ち。dev warning でどの key が重複したか表示されます
+- **CSP nonce**: Phase 1 では伝搬しません。`nonce` attr は型上は宣言してありますが今のところ無視されます
+- **strategy**: `afterInteractive` は外部 script に `async` を付ける。`lazyOnload` は `defer`。明示的な `async` / `defer` が常に勝ち。`beforeInteractive` は非対応
+### runtime が描画する形
+各プラグインについて runtime が `publicHead(ctx)` (resp. `publicBodyEnd`) を呼び、descriptor を validate して reject を drop、残ったものを `<Fragment>` でラップ。root layout はその Fragment を直接埋め込みます:
+```tsx
+<head>{pluginHead}</head>
+{/* … */}
+<body>… {pluginBodyEnd}</body>
+```
+`cms.config.plugins` の順序は集約後も保たれます。
+---
+## 7. 非同期イベントフック
+`hooks` は SQS から到着したイベントを trust_level に対応する processor Lambda が受けて実行します。runtime context (`ctx`) の中身:
+```ts
+interface PluginRuntimeContext {
+  site: Config['site']
+  listPublishedPosts(): Promise<Post[]>   // trusted のみ
+  writePublicAsset(key: string, body, contentType): Promise<string>  // trusted のみ
+}
+```
+例: RSS プラグイン ([`packages/plugin-rss/src/index.ts`](https://github.com/heavymoons/ampless/blob/main/packages/plugin-rss/src/index.ts) 参照):
+```ts
+hooks: {
+  'content.published': async (_event, ctx) => {
+    const posts = await ctx.listPublishedPosts()
+    const xml = buildRssFeed(posts, ctx.site)
+    await ctx.writePublicAsset('feed.xml', xml, 'application/rss+xml')
+  },
+  'content.unpublished': /* 同じ */,
+  'content.deleted': /* 同じ */,
+  'content.updated': /* 同じ */,
+}
+```
+### ベストプラクティス
+- **冪等にする**。SQS は at-least-once 配送 — 同じイベントが 2 回 fire する可能性があります。同じ入力で同じ出力 (決定論的なフィード等) を生成するようにしてください
+- **宣言していない `event.payload.*` を読まない**。形は [`docs/architecture/05-event-system.md`](https://github.com/heavymoons/ampless/blob/main/docs/architecture/05-event-system.md) に文書化されています。形がドリフトすると暗黙の読み出しが silent に壊れます
+- **エラーは DLQ に行く**。フック内で throw すると最終的にメッセージは dead-letter queue に届きます。失敗のサーフェスは通常の CloudWatch ダッシュボードで
+---
+## 8. `settings.public` — admin 管理の値 (Phase 2)
+`settings.public` マニフェストを宣言すると、ホストには `/admin/plugins` の編集 UI が自動で生えます。
+```ts
+settings: {
+  public: [
+    {
+      type: 'text',
+      key: 'measurementId',
+      label: { en: 'Measurement ID', ja: '測定 ID' },
+      description: { en: 'GA4 ID, blank to disable', ja: '空で無効化' },
+      pattern: '^$|^G-[A-Z0-9]+$',
+      placeholder: 'G-XXXXXXXX',
+      default: 'G-XXXXXXXX',
+    },
+  ],
+}
+```
+### 利用可能な field タイプ
+| Type | 保存形 | 補足 |
+|---|---|---|
+| `text` | string | `pattern`、`maxLength`、`placeholder` |
+| `textarea` | string | `rows`、`maxLength` |
+| `url` | string | save 時に scheme チェック、`allowRelative` |
+| `code` | string | `language` ラベル (表示用)、Phase 2.5 で専用エディタに差し替え予定 |
+| `boolean` | boolean | チェックボックスで描画 |
+| `number` | number | `min` / `max` / `step` |
+| `select` | string (`options[i].value` のいずれかと一致必須) | `options` 必須 |
+| `json` | decoded value (object / array / number / boolean) | admin form は save 前に `JSON.parse` |
+### 保存形
+保存される値は DynamoDB の以下に landing:
+```
+pk = 'siteconfig'
+sk = 'plugins.<instanceId>.<fieldKey>'
+```
+trusted processor がこの行を S3 の `public/site-settings.json` にミラー。`publicHead` / `publicBodyEnd` 実行時に公開 runtime がこの file を fetch (60s `revalidate`、`site-settings` cache tag) し、描画パス内から同期読み出しできるようになります。
+### required / 無効化 / 未設定 の違い
+- `required: true` は save 時に empty / undefined を reject、admin form にエラー表示
+- **string 系 field** (`text` / `textarea` / `url` / `code`) は、`required` が falsy のとき **空文字保存が valid**。これが「無効化」シグナル — 例えば GA4 では `measurementId` を空文字保存することで、プラグインを削除せず解析を停止できます
+- **非 string 系 field** (`number` / `boolean` / `json` / `select`) は常に空文字 reject。保存値をクリアしたい場合はユーザが **デフォルトに戻す** を押す — DDB 行が削除され、次のリクエストから `manifest.default` にフォールバックします
+---
+## 9. 設定値の読み出し: `ctx.setting<T>(key)`
+`publicHead` / `publicBodyEnd` 内で解決済みの値を読み出すには `ctx.setting`:
+```ts
+publicHead(ctx) {
+  const id = ctx.setting<string>('measurementId') ?? ''
+  if (!id) return []
+  return [/* id を使った descriptor */]
+}
+```
+リクエスト毎の解決順序:
+```
+stored 値 (validated)
+  ↳ manifest.default (これも validated)
+    ↳ undefined
+```
+両側で validation を通すので、手で DDB 行を編集した結果 out-of-range になった値 (あるいは constructor 引数として渡された壊れた default) がページに漏れません。renderer は invalid 値を「存在しない」かのように扱い、次の valid 層が引き継ぎます。
+スナップショットがいつ更新されるか: trusted processor が `public/site-settings.json` の再生成を完了した後、次の Next.js fetch cache TTL (60s) を過ぎたリクエストから新値を読みます。admin form は cache invalidation を ~8s 遅延発火するので、processor の S3 rebuild が完了する前に公開側が古い JSON を fetch して詰めてしまう race を避けています。
+### 複数インスタンス
+各プラグインインスタンスは `instanceId` でスコープされた独立 namespace を持ちます。`cms.config.ts` 内の 2 回の `analyticsGa4Plugin({ instanceId: 'a' })` と `analyticsGa4Plugin({ instanceId: 'b' })` は別々の DDB 行を見ます。`ctx.setting()` は自プラグインの `instanceId` に自動スコープします。
+---
+## 10. ウォークスルー: GA4 を Phase 1 から Phase 2 に移行する
+Phase 1 の GA4 プラグインは measurement ID を constructor 引数で受けていました。Phase 2 では後方互換のためにその引数を残しつつ、値は `ctx.setting()` 経由で読みます。
+**Before** (Phase 1):
+```ts
+export default function analyticsGa4Plugin(opts: { measurementId: string }) {
+  const { measurementId } = opts
+  return definePlugin({
+    name: 'analytics-ga4',
+    apiVersion: 1,
+    trust_level: 'untrusted',
+    capabilities: ['publicHead'],
+    publicHead() {
+      if (!measurementId) return []
+      return [/* measurementId を使う descriptor */]
+    },
+  })
+}
+```
+**After** (Phase 2):
+```ts
+export default function analyticsGa4Plugin(opts: { measurementId?: string } = {}) {
+  const { measurementId = '', instanceId = 'analytics-ga4' } = opts
+  return definePlugin({
+    name: 'analytics-ga4',
+    instanceId,
+    apiVersion: 1,
+    trust_level: 'untrusted',
+    capabilities: ['publicHead', 'adminSettings'],
+    settings: {
+      public: [{
+        type: 'text',
+        key: 'measurementId',
+        label: { en: 'Measurement ID', ja: '測定 ID' },
+        pattern: '^$|^G-[A-Z0-9]+$',
+        default: measurementId,
+      }],
+    },
+    publicHead(ctx) {
+      const id = ctx.setting<string>('measurementId') ?? ''
+      if (!id) return []
+      return [/* id を使う descriptor */]
+    },
+  })
+}
+```
+constructor 引数は `manifest.default` の seed になります。`cms.config.ts` で既に `analyticsGa4Plugin({ measurementId: 'G-X' })` を渡している運用者は挙動変化なし。新規デプロイは空にして admin UI 側で設定する運用が推奨です。
+---
+## 11. テスト
+ampless は vitest を使っています。典型的なプラグインテストはこんな形:
+```ts
+import { describe, it, expect } from 'vitest'
+import type { PluginPublicRenderContext, AmplessPlugin } from 'ampless'
+import { resolvePluginSettings } from 'ampless'
+import myPlugin from './index.js'
+function makeCtx(plugin: AmplessPlugin, stored: Record<string, unknown> = {}): PluginPublicRenderContext {
+  const resolved = resolvePluginSettings(plugin.settings, stored)
+  return {
+    site: { name: 'Test', url: 'https://example.com/' },
+    setting: (k) => resolved[k],
+  }
+}
+it('measurementId 設定時に descriptor を吐く', () => {
+  const plugin = myPlugin({ measurementId: 'G-XXX' })
+  const descriptors = plugin.publicHead?.(makeCtx(plugin)) ?? []
+  expect(descriptors).toHaveLength(2)
+})
+it('admin が空文字保存した場合は空配列', () => {
+  const plugin = myPlugin({ measurementId: 'G-XXX' })
+  const descriptors = plugin.publicHead?.(makeCtx(plugin, { measurementId: '' })) ?? []
+  expect(descriptors).toEqual([])
+})
+```
+マニフェスト + 描画挙動をテストすればよいです。runtime の descriptor validator は `@ampless/runtime` 側でテストされているので、プラグインテストは「何の状態でどの descriptor を返すか」に集中してください。
+イベントフックのテストは `ctx.listPublishedPosts` と `ctx.writePublicAsset` を単純なスタブ関数で差し替えます。
+---
+## 12. npm publish
+ファーストパーティ / モノレポ内部のプラグインは本レポの既存 changeset フローに従ってください。外部プラグインは通常の npm パッケージ:
+- **パッケージ名**: `@your-scope/plugin-foo`。`@ampless/plugin-*` スコープは本モノレポから ship する公式プラグイン用に予約
+- **エントリ**: ESM のみ、default export (factory) + 設定インターフェイス (ユーザの `cms.config.ts` から型付きで引数を渡せるように) を export
+- **`apiVersion`**: 契約が変わるときだけ bump。既存フィールドの型が変わったら major、新フィールド追加なら minor (既存インストールは動き続ける)
+- **Dist-tag**: ampless 自体が alpha のうちは `@alpha`。`@latest` は ampless v1.0 まで予約
+参考実装:
+- [`packages/plugin-analytics-ga4`](https://github.com/heavymoons/ampless/tree/main/packages/plugin-analytics-ga4) — descriptor ベース、Phase 2 settings
+- [`packages/plugin-rss`](https://github.com/heavymoons/ampless/tree/main/packages/plugin-rss) — trusted、非同期 hooks + `writePublicAsset`
+- [`packages/plugin-seo`](https://github.com/heavymoons/ampless/tree/main/packages/plugin-seo) — `metadata()` + `siteMetadata()`
+- [`packages/plugin-webhook`](https://github.com/heavymoons/ampless/tree/main/packages/plugin-webhook) — untrusted hook + 外向き HTTP
+- [`packages/plugin-og-image`](https://github.com/heavymoons/ampless/tree/main/packages/plugin-og-image) — `ogImage` ルートレンダラ
+---
+## 13. 命名規則とよくある落とし穴
+### 命名規則
+- `name`、`instanceId`、`settings.public.key` のすべて: `/^[a-zA-Z0-9_-]+$/` 必須。違反した plugin / field は dev console warning 付きで runtime が drop します
+- `plugins.<instanceId>.<fieldKey>` のドット区切りが保存形式の唯一の構造です。key 側にネストしたドットを入れて凝らないでください
+### よくある落とし穴
+- **capability と実装の不一致**。`capabilities: ['publicHead']` を宣言したのに `publicHead` を未定義 (またはその逆) にすると、起動時に console warning が出ます。capability を外すか関数を追加してください
+- **`instanceId` 重複**。同じ namespace を共有する 2 つのインスタンスは起動時に警告が出ます。後者の保存設定は前者と衝突します
+- **`inlineScript` の `id` 忘れ**。production では silent に drop、dev では warn。inline script の dedup は id 無しではできません
+- **`publicHead` から `ReactNode` を返す**。TypeScript で弾かれます — `publicHead` の戻り値型は descriptor のみ。任意 `ReactNode` が必要なら、それは Phase 6b の `developer.headElements` capability 待ち
+- **admin form から `manifest.default` を保存してしまう**。resolved default を「明示値」として書き戻さないでください — admin form が touched フィールドのみ書き込む設計はまさにこのため。default 値を保存すると future のパッケージ更新で default が変わってもそのフィールドだけ反映されなくなります
+---
+## 14. 質問先
+- アーキテクチャ / 設計の質問 → [`docs/architecture/08-plugin-architecture.ja.md`](https://github.com/heavymoons/ampless/blob/main/docs/architecture/08-plugin-architecture.ja.md)
+- ファーストパーティプラグインの bug → `heavymoons/ampless` にプラグインの package 名つきで issue
+- プラグインランタイム / admin form の bug → 同じレポ、ラベル `area:plugins`
+ampless レポは v1.0 RC まで非公開なので、上記のリンクは現時点では package tarball 内の `node_modules/ampless/docs/` をローカルで見るための参照です。public 化後は実 GitHub URL に解決されます。

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

@@ -0,0 +1,630 @@
+<!--
+  Source of truth lives in packages/ampless/docs/plugin-author-guide.md.
+  Keep both copies in sync — the scaffold copy at
+  templates/_shared/docs/plugin-author-guide.md must mirror this file
+  byte-for-byte until we add a CI check.
+-->
+> 日本語版: [plugin-author-guide.ja.md](./plugin-author-guide.ja.md)
+# Writing an ampless plugin
+This guide walks through everything a plugin author needs to ship a
+working ampless plugin, from first `definePlugin()` call to the
+admin-editable settings panel and an npm publish. It covers the
+Phase 1 + Phase 2 surfaces — descriptor-based `<head>` / `<body>`
+injection, the async event hooks, and admin-managed
+`settings.public` values.
+The design rationale is in [`docs/architecture/08-plugin-architecture.md`](https://github.com/heavymoons/ampless/blob/main/docs/architecture/08-plugin-architecture.md);
+this page is the hands-on companion.
+---
+## 1. What a plugin can do
+An ampless plugin is a TypeScript module that returns an
+`AmplessPlugin` object. It plugs into one or more of the following
+surfaces:
+| Surface | Where | Sync / async | Phase |
+|---|---|---|---|
+| `metadata(post, site)` | `generateMetadata()` per post | sync | Existing |
+| `siteMetadata(site)` | root layout `generateMetadata()` | sync | Existing |
+| `publicHead(ctx)` | root layout `<head>` | sync (called from async layout) | 1 |
+| `publicBodyEnd(ctx)` | root layout end of `<body>` | sync | 1 |
+| `ogImage` | `/og/[slug]` route | request-time, in public Lambda | Existing |
+| `hooks` | trust_level-matched processor Lambda | async, on SQS event | Existing |
+| `settings.public` | `/admin/plugins` form | declarative manifest | 2 |
+What a plugin **cannot** do today (without privileged tier work, see
+roadmap):
+- Inject arbitrary `ReactNode` into pages — descriptor variants only.
+- Open a TCP socket in the public Next.js process. Trusted Lambdas
+  have outbound HTTP only.
+- Add admin routes / server routes / content fields — those
+  capabilities are reserved for Phase 6b.
+- Read or write secrets. The `secretSettings` capability is reserved
+  for Phase 6a.
+---
+## 2. Minimum file layout
+A plugin can ship as a tiny npm package or live in your site's
+monorepo. The on-disk shape is the same either way:
+```
+my-plugin/
+  package.json
+  tsconfig.json
+  tsup.config.ts
+  src/
+    index.ts
+    index.test.ts
+```
+See `packages/plugin-rss/` and `packages/plugin-analytics-ga4/` in
+this repo for working examples.
+The bare-minimum `src/index.ts`:
+```ts
+import { definePlugin, type AmplessPlugin } from 'ampless'
+export default function myPlugin(): AmplessPlugin {
+  return definePlugin({
+    name: 'my-plugin',
+    apiVersion: 1,
+    trust_level: 'untrusted',
+    capabilities: ['publicHead'],
+    publicHead() {
+      return [{ type: 'meta', name: 'x-plugin', content: 'hi' }]
+    },
+  })
+}
+```
+Drop it into `cms.config.ts`:
+```ts
+import myPlugin from 'my-plugin'
+export default defineConfig({
+  site: { name: 'My Blog', url: 'https://example.com' },
+  plugins: [myPlugin()],
+})
+```
+That's it. Restart `npm run dev`, view source on any page, and the
+`<meta name="x-plugin" content="hi" />` is in the rendered `<head>`.
+---
+## 3. The `AmplessPlugin` manifest
+```ts
+interface AmplessPlugin {
+  name: string                      // package-like identifier, e.g. 'analytics-ga4'
+  apiVersion: 1                     // bump only when the contract changes
+  trust_level: 'untrusted' | 'trusted' | 'privileged'
+  instanceId?: string               // namespace for multi-instance installs
+  displayName?: LocalizedString     // admin UI label
+  capabilities?: readonly PluginCapability[]
+  hooks?: { ... }                   // async events
+  metadata?(post, site): PluginMetadata
+  siteMetadata?(site): PluginMetadata
+  publicHead?(ctx): readonly PublicHeadDescriptor[]
+  publicBodyEnd?(ctx): readonly PublicBodyDescriptor[]
+  ogImage?: OgImageConfig
+  settings?: { public?: readonly PluginSettingField[] }
+}
+```
+### `name`
+A short identifier (`'analytics-ga4'`, `'rss'`, `'webhook'`). Used
+as the default `instanceId` and as the trusted-processor S3 prefix
+under `public/plugins/<name>/`. Must match `/^[a-zA-Z0-9_-]+$/` —
+see "Naming rules" below.
+### `apiVersion: 1`
+There's only one version today. Future breaking-change versions will
+bump this number; the runtime rejects unknown values rather than
+silently mis-binding.
+### `instanceId`
+Optional, defaults to `name`. When you ship a plugin that can run
+twice on the same site (e.g. two GA4 measurement IDs, or one
+webhook endpoint per chat platform), let the host customise
+`instanceId` so each install gets its own storage namespace:
+```ts
+analyticsGa4Plugin({ instanceId: 'marketing' })
+analyticsGa4Plugin({ instanceId: 'product' })
+```
+Both `instanceId` and `name` must satisfy `/^[a-zA-Z0-9_-]+$/`. Dots
+break the `pk='siteconfig', sk='plugins.<id>.<key>'` separator;
+scopes (`@foo/bar`) and slashes are reserved.
+### `displayName`
+What `/admin/plugins` shows as the panel heading. A plain string is
+fine for single-locale plugins; the per-locale map form
+(`{ en: 'GA4', ja: 'GA4' }`) reads from the admin's active locale.
+---
+## 4. Picking a `trust_level`
+Three tiers, picked by what the plugin needs to do **inside
+event hooks** (the sync surfaces — metadata, head, body — don't
+touch IAM):
+| Tier | IAM | Used by |
+|---|---|---|
+| `untrusted` | none (SQS consume only) | head/body descriptors, webhook delivery, content transforms |
+| `trusted` | read posts, write `public/plugins/<name>/...` | RSS feed, sitemap, computed JSON indexes |
+| `privileged` | reserved | future: SES, secrets, private S3 |
+Rule of thumb:
+- **You only need `publicHead` / `publicBodyEnd` / `metadata`** →
+  `untrusted`.
+- **You need to read posts from a hook (e.g. rebuild a feed on
+  publish)** → `trusted`.
+- **You need to call AWS APIs other than S3 PutObject on
+  `public/plugins/*`** → don't ship a plugin yet; wait for the
+  privileged tier or write the integration outside the plugin
+  system.
+A plugin running at the wrong trust level either has no permission
+to do its job (silent failure inside the Lambda) or carries
+permissions it didn't need. Both are fixable by switching tiers and
+redeploying.
+---
+## 5. Sync surfaces
+These run inside the **public Next.js process** (the site visitor's
+request thread). They are pure with respect to AWS — no IAM, no
+network — and execute synchronously.
+| Surface | Returns | Use case |
+|---|---|---|
+| `metadata(post, site)` | `PluginMetadata` (Next.js `Metadata`-shaped) | Per-post `<title>` / OGP / Twitter / canonical |
+| `siteMetadata(site)` | `PluginMetadata` | Site-wide `<title>` / favicon / RSS `<link rel="alternate">` |
+| `publicHead(ctx)` | `PublicHeadDescriptor[]` | Analytics loader, fonts, jsonld, hreflang |
+| `publicBodyEnd(ctx)` | `PublicBodyDescriptor[]` | GTM no-script frame, chat widgets, tail snippets |
+The `ctx` object carries:
+```ts
+{
+  site: Config['site']      // name / url / description
+  setting<T>(key: string): T | undefined
+}
+```
+`ctx.setting()` is the Phase 2 admin-managed values accessor — see
+§8.
+---
+## 6. Descriptor reference
+`publicHead` and `publicBodyEnd` return **descriptor objects**, not
+`ReactNode`. The runtime validates them, then builds the React
+elements itself. This is the safety boundary that lets ampless run
+untrusted code in the public render path.
+### Common variants
+```ts
+// External script
+{
+  type: 'script',
+  id: 'ga4-loader-analytics-ga4',
+  src: 'https://www.googletagmanager.com/gtag/js?id=G-XXX',
+  strategy: 'afterInteractive', // or 'lazyOnload'
+  async: true,                  // optional; strategy implies it
+  defer: false,
+  attrs: { crossorigin: 'anonymous' },
+}
+// Inline script — id REQUIRED so two plugins emitting near-identical
+// snippets are dedup-able
+{
+  type: 'inlineScript',
+  id: 'ga4-init-analytics-ga4',
+  body: "/* one-line bootstrap */",
+  strategy: 'afterInteractive',
+}
+// Meta / link / noscript
+{ type: 'meta', name: 'theme-color', content: '#fff' }
+{ type: 'meta', property: 'og:image', content: 'https://…' }
+{ type: 'link', rel: 'preconnect', href: 'https://cdn.example.com' }
+{ type: 'noscript', id: 'gtm-fallback-msg', html: '<p>JS required</p>' }
+```
+### Body-only variant
+```ts
+// iframe — for GTM no-script fallback, chat widgets, etc.
+{
+  type: 'iframe',
+  id: 'gtm-fallback',
+  src: 'https://www.googletagmanager.com/ns.html?id=GTM-XYZ',
+  height: 0,
+  width: 0,
+  attrs: { sandbox: 'allow-scripts' },
+}
+```
+### Validation rules
+- **URL scheme allowlist**: `http`, `https`, or relative paths.
+  `javascript:`, `data:`, `vbscript:`, `blob:`, `file:` are rejected
+  before the element is rendered.
+- **`attrs` allowlist**: `data-*`, `crossorigin`, `referrerpolicy`,
+  `integrity`, `fetchpriority`, `loading`, `sandbox`, `allow`,
+  `allowfullscreen`. Anything else is dropped with a dev warning.
+- **`inlineScript.id` required**. Without it, two plugins emitting
+  the same snippet can't be dedup'd, and dev warnings would point at
+  index numbers no one can map back to a plugin.
+- **Duplicate `id`**: the last occurrence wins. A dev warning prints
+  which key was duplicated.
+- **CSP nonce**: not propagated in Phase 1. The `nonce` attr is
+  declared in the type for forward-compat but discarded today.
+- **Strategy**: `afterInteractive` adds `async` to external scripts.
+  `lazyOnload` adds `defer`. Explicit `async` / `defer` always
+  wins. `beforeInteractive` is not supported.
+### What the runtime renders
+For each plugin, the runtime calls `publicHead(ctx)` (resp.
+`publicBodyEnd`), validates every descriptor, drops the rejects,
+and wraps the survivors into a `<Fragment>`. The root layout
+interpolates that fragment directly:
+```tsx
+<head>{pluginHead}</head>
+{/* … */}
+<body>… {pluginBodyEnd}</body>
+```
+`cms.config.plugins` iteration order is preserved across the
+collected list.
+---
+## 7. Async event hooks
+`hooks` runs inside the trust_level-matched processor Lambda when an
+event arrives via SQS. The runtime context (`ctx`) carries:
+```ts
+interface PluginRuntimeContext {
+  site: Config['site']
+  listPublishedPosts(): Promise<Post[]>   // trusted only
+  writePublicAsset(key: string, body, contentType): Promise<string>  // trusted only
+}
+```
+Example: RSS plugin (see [`packages/plugin-rss/src/index.ts`](https://github.com/heavymoons/ampless/blob/main/packages/plugin-rss/src/index.ts)):
+```ts
+hooks: {
+  'content.published': async (_event, ctx) => {
+    const posts = await ctx.listPublishedPosts()
+    const xml = buildRssFeed(posts, ctx.site)
+    await ctx.writePublicAsset('feed.xml', xml, 'application/rss+xml')
+  },
+  'content.unpublished': /* same */,
+  'content.deleted': /* same */,
+  'content.updated': /* same */,
+}
+```
+### Best practices
+- **Be idempotent.** SQS delivery is at-least-once: the same event
+  may fire twice. Writing the same output twice should produce the
+  same effect (e.g. a deterministic feed).
+- **Don't read events.payload.\* fields you didn't declare.** The
+  shape is documented in [`docs/architecture/05-event-system.md`](https://github.com/heavymoons/ampless/blob/main/docs/architecture/05-event-system.md);
+  drifting consumers break silently when the shape moves.
+- **Errors propagate to DLQ.** Throwing inside a hook eventually
+  parks the message in the dead-letter queue. Use the normal
+  CloudWatch dashboards to surface failures.
+---
+## 8. `settings.public` — admin-managed values (Phase 2)
+Declare a `settings.public` manifest and the host gets a
+`/admin/plugins` editor for those values automatically.
+```ts
+settings: {
+  public: [
+    {
+      type: 'text',
+      key: 'measurementId',
+      label: { en: 'Measurement ID', ja: '測定 ID' },
+      description: { en: 'GA4 ID, blank to disable', ja: '空で無効化' },
+      pattern: '^$|^G-[A-Z0-9]+$',
+      placeholder: 'G-XXXXXXXX',
+      default: 'G-XXXXXXXX',
+    },
+  ],
+}
+```
+### Available field types
+| Type | Stored as | Notes |
+|---|---|---|
+| `text` | string | `pattern`, `maxLength`, `placeholder` |
+| `textarea` | string | `rows`, `maxLength` |
+| `url` | string | scheme-checked at save time, `allowRelative` |
+| `code` | string | `language` label (display only), Phase 2.5 will swap in a dedicated editor |
+| `boolean` | boolean | rendered as checkbox |
+| `number` | number | `min` / `max` / `step` |
+| `select` | string (matches one `options[i].value`) | required to be in `options` |
+| `json` | decoded value (object / array / number / boolean) | admin form `JSON.parse`s before saving |
+### Storage shape
+Each saved value lands in DynamoDB at:
+```
+pk = 'siteconfig'
+sk = 'plugins.<instanceId>.<fieldKey>'
+```
+The trusted processor mirrors the row to `public/site-settings.json`
+in S3. The public runtime fetches that file (60 s `revalidate`,
+`site-settings` cache tag) when `publicHead` / `publicBodyEnd` run,
+giving you cheap synchronous reads from inside the render path.
+### Required vs disabled vs unset
+- `required: true` rejects empty / undefined values at save time
+  and surfaces an admin form error.
+- For **string-like fields** (`text` / `textarea` / `url` / `code`),
+  saving an empty string is **valid** when `required` is falsy.
+  It's the "disable" sentinel — e.g. GA4 saves an empty
+  `measurementId` to turn analytics off without removing the
+  plugin.
+- For **non-string fields** (`number` / `boolean` / `json` /
+  `select`), empty string is always rejected. To clear a stored
+  value entirely, the user clicks **Reset to default** — that
+  deletes the DDB row so the next request falls back to
+  `manifest.default`.
+---
+## 9. Reading settings: `ctx.setting<T>(key)`
+Inside `publicHead` / `publicBodyEnd`, read the resolved value via
+`ctx.setting`:
+```ts
+publicHead(ctx) {
+  const id = ctx.setting<string>('measurementId') ?? ''
+  if (!id) return []
+  return [/* descriptors using id */]
+}
+```
+Resolution order, per request:
+```
+stored value (validated)
+  ↳ manifest.default (also validated)
+    ↳ undefined
+```
+Validation runs on both sides so a manually-edited DDB row that's
+out of range (or a malformed constructor argument seeded as
+`default`) doesn't leak into the page. The renderer treats invalid
+values as if they didn't exist; the next valid layer takes over.
+When does the snapshot update? When the trusted processor finishes
+rebuilding `public/site-settings.json`, the next request inside the
+~60 s Next.js fetch cache window still serves the old version. The
+admin form deliberately delays its cache-invalidation call by ~8 s
+so the rebuild has time to finish before the public side hits
+origin.
+### Multiple instances
+Each plugin instance has its own settings namespace keyed by
+`instanceId`. Two `analyticsGa4Plugin({ instanceId: 'a' })` and
+`analyticsGa4Plugin({ instanceId: 'b' })` calls in `cms.config.ts`
+get distinct DDB rows; `ctx.setting()` automatically scopes to the
+plugin's own `instanceId`.
+---
+## 10. Walk-through: migrating GA4 from Phase 1 to Phase 2
+The Phase 1 GA4 plugin took the measurement ID through a
+constructor argument. Phase 2 keeps the argument for backward
+compatibility but reads the live value from `ctx.setting()`.
+**Before** (Phase 1):
+```ts
+export default function analyticsGa4Plugin(opts: { measurementId: string }) {
+  const { measurementId } = opts
+  return definePlugin({
+    name: 'analytics-ga4',
+    apiVersion: 1,
+    trust_level: 'untrusted',
+    capabilities: ['publicHead'],
+    publicHead() {
+      if (!measurementId) return []
+      return [/* descriptors using measurementId */]
+    },
+  })
+}
+```
+**After** (Phase 2):
+```ts
+export default function analyticsGa4Plugin(opts: { measurementId?: string } = {}) {
+  const { measurementId = '', instanceId = 'analytics-ga4' } = opts
+  return definePlugin({
+    name: 'analytics-ga4',
+    instanceId,
+    apiVersion: 1,
+    trust_level: 'untrusted',
+    capabilities: ['publicHead', 'adminSettings'],
+    settings: {
+      public: [{
+        type: 'text',
+        key: 'measurementId',
+        label: { en: 'Measurement ID', ja: '測定 ID' },
+        pattern: '^$|^G-[A-Z0-9]+$',
+        default: measurementId,
+      }],
+    },
+    publicHead(ctx) {
+      const id = ctx.setting<string>('measurementId') ?? ''
+      if (!id) return []
+      return [/* descriptors using id */]
+    },
+  })
+}
+```
+The constructor argument now seeds `manifest.default`. Operators
+that already set `analyticsGa4Plugin({ measurementId: 'G-X' })` in
+`cms.config.ts` keep their current behaviour; new deployments
+should leave it empty and configure the value from the admin UI.
+---
+## 11. Testing
+ampless uses vitest. Plugin tests typically look like:
+```ts
+import { describe, it, expect } from 'vitest'
+import type { PluginPublicRenderContext, AmplessPlugin } from 'ampless'
+import { resolvePluginSettings } from 'ampless'
+import myPlugin from './index.js'
+function makeCtx(plugin: AmplessPlugin, stored: Record<string, unknown> = {}): PluginPublicRenderContext {
+  const resolved = resolvePluginSettings(plugin.settings, stored)
+  return {
+    site: { name: 'Test', url: 'https://example.com/' },
+    setting: (k) => resolved[k],
+  }
+}
+it('emits descriptors when measurementId is set', () => {
+  const plugin = myPlugin({ measurementId: 'G-XXX' })
+  const descriptors = plugin.publicHead?.(makeCtx(plugin)) ?? []
+  expect(descriptors).toHaveLength(2)
+})
+it('returns empty when admin saved empty string', () => {
+  const plugin = myPlugin({ measurementId: 'G-XXX' })
+  const descriptors = plugin.publicHead?.(makeCtx(plugin, { measurementId: '' })) ?? []
+  expect(descriptors).toEqual([])
+})
+```
+Test the manifest + the rendering behaviour. The runtime's
+descriptor validator is exercised in `@ampless/runtime` already —
+plugin tests focus on the *what* (which descriptors get returned for
+which state), not the validation surface.
+For event hooks, mock `ctx.listPublishedPosts` and
+`ctx.writePublicAsset` with simple stub functions.
+---
+## 12. Publishing to npm
+For first-party / monorepo-internal plugins, follow the changeset
+flow already in this repo. For external plugins, the shape is just
+a normal npm package:
+- **Name**: `@your-scope/plugin-foo`. The `@ampless/plugin-*`
+  scope is reserved for first-party plugins shipped from this
+  monorepo.
+- **Entry**: ESM only, exports default (the factory) and the
+  config interface (for typed args in user `cms.config.ts`).
+- **`apiVersion`**: bump only when the contract changes. Bump
+  major when an existing field's type changes; bump minor when you
+  add a new field (existing installs keep working).
+- **Dist-tag**: `@alpha` while ampless itself is in alpha. The
+  `@latest` tag stays reserved until ampless v1.0.
+Worked examples to crib from:
+- [`packages/plugin-analytics-ga4`](https://github.com/heavymoons/ampless/tree/main/packages/plugin-analytics-ga4) — descriptor-based, Phase 2 settings.
+- [`packages/plugin-rss`](https://github.com/heavymoons/ampless/tree/main/packages/plugin-rss) — trusted, async event hooks + `writePublicAsset`.
+- [`packages/plugin-seo`](https://github.com/heavymoons/ampless/tree/main/packages/plugin-seo) — `metadata()` + `siteMetadata()`.
+- [`packages/plugin-webhook`](https://github.com/heavymoons/ampless/tree/main/packages/plugin-webhook) — untrusted hook with outbound HTTP.
+- [`packages/plugin-og-image`](https://github.com/heavymoons/ampless/tree/main/packages/plugin-og-image) — `ogImage` route renderer.
+---
+## 13. Naming rules + common pitfalls
+### Naming rules
+- `name`, `instanceId`, every `settings.public.key`: must match
+  `/^[a-zA-Z0-9_-]+$/`. The runtime drops plugins / fields that
+  violate this with a dev console warning.
+- The dot separator in `plugins.<instanceId>.<fieldKey>` is the
+  only structure the storage format relies on. Don't try to be
+  clever with nested dots in your keys.
+### Common pitfalls
+- **Capability + implementation mismatch.** Declaring
+  `capabilities: ['publicHead']` but never defining `publicHead` (or
+  vice versa) prints a console warning at startup. Either drop the
+  capability or add the function.
+- **Duplicate `instanceId`.** Two plugin instances sharing the same
+  namespace get a startup warning. The second one's stored settings
+  collide with the first.
+- **Forgetting `id` on `inlineScript`.** The descriptor is dropped
+  silently in production and warned in dev. There is no way for
+  the runtime to dedup inline scripts without an id.
+- **Returning `ReactNode` from `publicHead`.** TypeScript catches
+  this — `publicHead` is typed to return descriptors only. If you
+  find yourself needing arbitrary `ReactNode`, that's the Phase 6b
+  `developer.headElements` capability waiting to land.
+- **Saving `manifest.default` through the admin form.** Don't write
+  the resolved default back as if it were an explicit value — the
+  admin form only writes touched fields for exactly this reason.
+  Saving a default value freezes it: future package updates that
+  change the default won't take effect for that field anymore.
+---
+## 14. Where to ask
+- Architecture / design questions → [`docs/architecture/08-plugin-architecture.md`](https://github.com/heavymoons/ampless/blob/main/docs/architecture/08-plugin-architecture.md)
+- Bugs in a first-party plugin → file an issue against
+  `heavymoons/ampless` referencing the plugin's package name.
+- Bugs in the plugin runtime / admin form → same repo, label
+  `area:plugins`.
+The ampless repo stays private until v1.0 RC. Once it's public, the
+links above resolve to the actual GitHub URLs; today they live in
+the package tarball directly under `node_modules/ampless/docs/`.

package/dist/templates/_shared/package.json CHANGED Viewed

@@ -25,15 +25,15 @@
     "@tiptap/pm": "^3.23.6",
     "@tiptap/react": "^3.23.6",
     "@tiptap/starter-kit": "^3.23.6",
-    "@ampless/plugin-og-image": "^0.2.0-alpha.16",
-    "@ampless/plugin-rss": "^0.2.0-alpha.16",
-    "@ampless/plugin-seo": "^0.2.0-alpha.16",
-    "@ampless/plugin-webhook": "^0.2.0-alpha.16",
-    "@ampless/admin": "^1.0.0-alpha.40",
-    "@ampless/backend": "^1.0.0-alpha.31",
-    "@ampless/runtime": "^1.0.0-alpha.22",
+    "@ampless/plugin-og-image": "^0.2.0-alpha.18",
+    "@ampless/plugin-rss": "^0.2.0-alpha.18",
+    "@ampless/plugin-seo": "^0.2.0-alpha.18",
+    "@ampless/plugin-webhook": "^0.2.0-alpha.18",
+    "@ampless/admin": "^1.0.0-alpha.42",
+    "@ampless/backend": "^1.0.0-alpha.33",
+    "@ampless/runtime": "^1.0.0-alpha.24",
     "@digital-go-jp/tailwind-theme-plugin": "^0.3.4",
-    "ampless": "^1.0.0-alpha.16",
+    "ampless": "^1.0.0-alpha.18",
     "aws-amplify": "^6.17.0",
     "class-variance-authority": "^0.7.1",
     "clsx": "^2.1.1",

package/package.json CHANGED Viewed

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