ampless 1.0.0-alpha.22 → 1.0.0-alpha.24

package/dist/index.d.ts

@@ -615,7 +615,33 @@ interface PluginJsonField extends PluginFieldBase<unknown> {
     placeholder?: string;
     rows?: number;
 }
-type PluginSettingField = PluginTextField | PluginTextareaField | PluginBooleanField | PluginNumberField | PluginSelectField | PluginUrlField | PluginCodeField | PluginJsonField;
+/**
+ * Sub-fields allowed inside a `PluginRepeatableField`. Restricted to
+ * the scalar-shape field types so the v1 admin editor can render each
+ * cell with the existing `renderScalarInput` seam. Code / json /
+ * repeatable are excluded — code is rarely useful per-item, json
+ * recurses into "json inside json" UX that we explicitly want to
+ * avoid, and nested repeatable is deferred.
+ */
+type PluginRepeatableSubField = PluginTextField | PluginTextareaField | PluginBooleanField | PluginNumberField | PluginSelectField | PluginUrlField;
+interface PluginRepeatableField extends PluginFieldBase<ReadonlyArray<Readonly<Record<string, unknown>>>> {
+    type: 'repeatable';
+    /** Shape of each item — every item is a flat object keyed by sub-field `key`. */
+    fields: ReadonlyArray<PluginRepeatableSubField>;
+    /** Hard cap on item count (default 50). Exceeding rejects the whole field. */
+    maxItems?: number;
+    /** Minimum item count (default 0). Below rejects the whole field. */
+    minItems?: number;
+    /** Label for the "+ Add item" button in the admin editor. */
+    addLabel?: LocalizedString;
+    /**
+     * Sub-field key used as the per-item heading in the admin editor
+     * (e.g. `'id'` so categories[0] reads "analytics" not "Item 1").
+     * Falls back to "Item N" when absent or empty.
+     */
+    itemLabelKey?: string;
+}
+type PluginSettingField = PluginTextField | PluginTextareaField | PluginBooleanField | PluginNumberField | PluginSelectField | PluginUrlField | PluginCodeField | PluginJsonField | PluginRepeatableField;
 /**
  * Static manifest declared in a plugin package's `package.json` under
  * the `amplessPlugin` key. The plugin package must also expose
@@ -1186,7 +1212,7 @@ declare function isValidPluginKey(key: string): boolean;
  * `boolean`, `json` stores the decoded value (object / array /
  * primitive — never the source string), etc.
  */
-declare function validatePluginSettingValue(field: PluginSettingField, raw: unknown): unknown | null;
+declare function validatePluginSettingValue(field: PluginSettingField, raw: unknown, mode?: 'strict' | 'lenient'): unknown | null;
 /**
  * Merge stored values on top of manifest defaults for one plugin
  * instance. Both sides are validated through `validatePluginSettingValue`

package/dist/index.js

@@ -239,7 +239,7 @@ var PLUGIN_KEY_PATTERN = /^[a-zA-Z0-9_-]+$/;
 function isValidPluginKey(key) {
   return typeof key === "string" && PLUGIN_KEY_PATTERN.test(key);
 }
-function validatePluginSettingValue(field, raw) {
+function validatePluginSettingValue(field, raw, mode = "lenient") {
   if (raw === void 0) return null;
   switch (field.type) {
     case "text":
@@ -318,6 +318,60 @@ function validatePluginSettingValue(field, raw) {
       if (typeof raw === "string") return null;
       return raw;
     }
+    case "repeatable": {
+      if (!Array.isArray(raw)) return null;
+      const maxItems = typeof field.maxItems === "number" ? field.maxItems : 50;
+      const minItems = typeof field.minItems === "number" ? field.minItems : 0;
+      if (raw.length > maxItems) return null;
+      if (raw.length < minItems) return null;
+      const subFieldMap = /* @__PURE__ */ new Map();
+      for (const sf of field.fields) {
+        subFieldMap.set(sf.key, sf);
+      }
+      const validatedItems = [];
+      for (const item of raw) {
+        if (typeof item !== "object" || item === null || Array.isArray(item)) {
+          if (mode === "strict") return null;
+          continue;
+        }
+        const rawItem = item;
+        let itemValid = true;
+        const validatedItem = {};
+        for (const sf of field.fields) {
+          const rawSubVal = Object.prototype.hasOwnProperty.call(rawItem, sf.key) ? rawItem[sf.key] : void 0;
+          if (rawSubVal === void 0) {
+            if (sf.required) {
+              if (mode === "strict") return null;
+              itemValid = false;
+              break;
+            }
+            if (sf.default !== void 0) {
+              const validatedDefault = validatePluginSettingValue(sf, sf.default, mode);
+              if (validatedDefault !== null) {
+                validatedItem[sf.key] = validatedDefault;
+              }
+            }
+            continue;
+          }
+          const validatedSubVal = validatePluginSettingValue(sf, rawSubVal, mode);
+          if (validatedSubVal === null) {
+            if (sf.required) {
+              if (mode === "strict") return null;
+              itemValid = false;
+              break;
+            }
+            continue;
+          }
+          validatedItem[sf.key] = validatedSubVal;
+        }
+        if (!itemValid) {
+          continue;
+        }
+        validatedItems.push(validatedItem);
+      }
+      if (validatedItems.length < minItems) return null;
+      return validatedItems;
+    }
   }
 }
 function resolvePluginSettings(manifest, stored) {

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

@@ -15,8 +15,49 @@
 
 ---
 
+## 0. テーマとプラグインの境界線
+
+ampless はテーマとプラグインの両方を提供します。用途に合ったものを選ぶことで、未来の自分や他のサイト作者が迷わずコードを見つけられます。
+
+| やりたいこと | テーマを使う | プラグインを使う |
+|---|---|---|
+| レイアウト・タイポグラフィ・配色・ルート単位の UI | ✓ | |
+| home / post / tag ページのカスタムコンポーネント | ✓ | |
+| 非開発者が admin から編集できる設定 | | ✓ (`adminSettings`) |
+| コンテンツイベント後のバックグラウンド処理（RSS・検索インデックス・webhook） | | ✓ (`eventHooks`) |
+| 信頼できる副作用（S3 書き込み・外部 API 送信） | | ✓ (`writePublicAsset` + `trusted`) |
+| テーマに依存しない `<head>` / `<body>` 注入（アナリティクス・同意バナー） | | ✓ (`publicHead` / `publicBodyEnd`) |
+| 投稿単位の機械可読メタデータ（JSON-LD 等） | | ✓ (`schema` via `publicBodyForPost`) |
+| 複数の ampless サイトで共有したいコード | | ✓ (npm パッケージとして公開) |
+
+判断の目安:
+
+- テーマ = **ページの見た目**。render 時は読み取り専用。
+- プラグイン = **render を超えて起こること**: admin 編集可能な設定、バックグラウンド処理、テーマ非依存の注入、機械可読メタデータ、サイト間の再利用。
+
+新しいプラグイン作者がよく踏む 2 つの境界線:
+
+- **ストレージ / DynamoDB / 外部 API 書き込みはプラグインに置く**。テーマは読み取り専用です。
+- **admin が `/admin/plugins` からオン・オフしたい機能はプラグインに置く**。表面上の効果が純粋に見た目だけであっても同様です。テーマも独自の設定を持てますが、それはテーマ表示設定であり、サイト運用設定ではありません。
+
+境界線上に本当に乗っている機能については [`docs/architecture/08-plugin-architecture.md`](https://github.com/heavymoons/ampless/blob/main/docs/architecture/08-plugin-architecture.md) で詳しく議論しています。
+
+---
+
 ## 1. プラグインで何ができるか
 
+ampless プラグインは 3 つのいずれかの場所に書きます — コードをどのくらい広く共有したいかに応じて選んでください:
+
+| どこに置くか | 使い時 | 置き場所 |
+|---|---|---|
+| **ファーストパーティ** | ampless コアへの全員向け貢献 | ampless モノレポ内の `packages/plugin-*/` |
+| **サイトローカル** | サイト固有のカスタマイズ、個別 publish 不要 | サイトリポジトリ内の `plugins/<name>/` |
+| **外部 npm パッケージ** | 他のサイトと共有したい、`npm publish` 想定 | スタンドアロンリポジトリ (`@scope/ampless-plugin-foo`) |
+
+3 つの形式はすべて同じ `definePlugin({...})` ファクトリを呼び出し、同じサーフェスを使います。違いはパッケージング・配布方法、および静的 `package.json#amplessPlugin` マニフェストが有効にするインストール時バリデーションのオプトインです（§3 参照）。
+
+§14 には一行のスキャフォールドコマンド (`npx create-ampless plugin <name>`) があり、後者 2 つのどちらにも即使えるボイラープレートを生成します。
+
 ampless プラグインは `AmplessPlugin` オブジェクトを返す TypeScript モジュールです。以下のうち 1 つ以上のサーフェスにフックします:
 
 | サーフェス | 実行場所 | 同期 / 非同期 | Phase |
@@ -30,30 +71,65 @@ ampless プラグインは `AmplessPlugin` オブジェクトを返す TypeScrip
 | `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 予約
+後続フェーズに残してある surface もいくつかあって、現状の `definePlugin`
+では形にできません:
+
+- **任意の `ReactNode` のページ注入**。同期描画 surface (`publicHead` /
+  `publicBodyEnd` / `publicBodyForPost`) は descriptor 変種を返すだけ。
+  descriptor の validator は **runtime が描画する HTML 出力の安全境界**
+  であって、プラグイン本体のコードを縛る JS sandbox ではない (プラグインは
+  普通の TypeScript としてサイトと同一の Node プロセス内で動く)
+- **同期描画 surface 内でのネットワーク**。これらの surface は宣言的な
+  出力を返す設計で、Promise を受け取らないし async result path も無い。
+  `publicHead` の中で `await fetch(...)` を書くと SSR が無期限ブロックする
+  (デッドラインを返す手段がない)。外向き HTTP が必要な処理は trusted
+  Lambda (`hooks`) でやる
+- **admin ルート / server ルート / コンテンツフィールドの追加** —
+  Phase 6b 予約
+- **secret の読み書き**。`secretSettings` capability は Phase 6a 予約。
+  `settings.public` に credential を置かないこと
 
 ---
 
 ## 2. 最小ファイル構成
 
-プラグインは小さな npm パッケージとして公開しても、サイトのモノレポ内に置いてもよいです。on-disk の構成はどちらでも同じ:
+プラグインを作る最速の方法はスキャフォールドです:
+
+```bash
+# サイトローカル (現在の ampless サイトに plugins/<name>/index.ts を生成)
+npx create-ampless@latest plugin my-thing
 
+# スタンドアロン npm パッケージ (`npm publish` 向けの ./<name>/ を生成)
+npx create-ampless@latest plugin @myscope/ampless-plugin-my-thing --standalone
 ```
-my-plugin/
+
+全体の手順は §14 を参照してください。このセクションの残りでは生成されるファイルの意味を説明します — 手書きしたい場合はここを読めば把握できます。
+
+### サイトローカル
+
+```
+plugins/
+  my-thing/
+    index.ts        # ファクトリ関数のみ。これがプラグインの全体
+```
+
+サイトの `package.json` / `tsconfig.json` がコンパイルを担うため、追加で ship するものはありません。`cms.config.ts` から相対 import で登録します。
+
+### スタンドアロン npm パッケージ
+
+```
+ampless-plugin-my-thing/
   package.json
   tsconfig.json
   tsup.config.ts
+  README.md
+  CHANGELOG.md
   src/
     index.ts
     index.test.ts
 ```
 
-本レポ内の `packages/plugin-rss/` と `packages/plugin-analytics-ga4/` が動作する参考実装です。
+本レポ内の `packages/plugin-rss/` と `packages/plugin-analytics-ga4/` が動作するファーストパーティの参考実装です — スタンドアロンスキャフォールドはこれらのレイアウトを踏襲します。
 
 最小の `src/index.ts`:
 
@@ -93,6 +169,7 @@ export default defineConfig({
 ```ts
 interface AmplessPlugin {
   name: string                      // パッケージ風の識別子。例: 'analytics-ga4'
+  packageName?: string              // インストール時のクロスチェック用 npm パッケージ名
   apiVersion: 1                     // 契約が変わるときだけ bump
   trust_level: 'untrusted' | 'trusted' | 'privileged'
   instanceId?: string               // 複数インストール時の namespace
@@ -132,6 +209,67 @@ analyticsGa4Plugin({ instanceId: 'product' })
 
 `/admin/plugins` のパネル見出し。単一ロケールのプラグインなら平文の文字列で十分。`{ en: 'GA4', ja: 'GA4' }` 形式の per-locale map にすると admin のアクティブロケールに応じて読み分けられます。
 
+### `packageName`
+
+省略可能。設定すると、runtime は起動時に `<packageName>/package.json` を解決し、そこにある静的な `amplessPlugin` ブロックをファクトリの戻り値とクロスチェックします。これにより、runtime で初めて気づく（あるいは永遠に気づかない）インストール時のミスを検出できます — capability の不一致はクラッシュせず、該当サーフェスが静かにスキップされるだけです。
+
+スタンドアロンプラグインでは、`package.json#name` で宣言している npm パッケージ名をここに設定します:
+
+```ts
+return definePlugin({
+  name: 'site-verification',
+  packageName: '@ishinao/ampless-plugin-site-verification',
+  apiVersion: 1,
+  // ...
+})
+```
+
+サイトローカルプラグインは不要です — 未設定のままにするとクロスチェックはスキップされます（Phase 5 より前のプラグインとの後方互換）。
+
+### `package.json` の静的マニフェスト（スタンドアロンプラグインのみ）
+
+クロスチェックが静的マニフェストを見つけるには、公開パッケージに 2 つの条件が必要です:
+
+1. `package.json#amplessPlugin` がファクトリの戻り値と同じフィールドを宣言している:
+
+   ```json
+   "amplessPlugin": {
+     "apiVersion": 1,
+     "name": "site-verification",
+     "trustLevel": "untrusted",
+     "capabilities": ["publicHead", "adminSettings"],
+     "displayName": { "en": "Site verification", "ja": "サイト所有権確認" }
+   }
+   ```
+
+2. `package.json#exports` が `./package.json` を明示的に公開している:
+
+   ```json
+   "exports": {
+     ".": {
+       "import": "./dist/index.js",
+       "types": "./dist/index.d.ts"
+     },
+     "./package.json": "./package.json"
+   }
+   ```
+
+   これがないと、Node のパッケージエクスポートの制約により `import.meta.resolve('<pkg>/package.json')` が `ERR_PACKAGE_PATH_NOT_EXPORTED` で拒否され、runtime はクロスチェックを静かにスキップします（プラグインは動きますが、インストール時ガードは機能しません）。
+
+`create-ampless plugin --standalone` スキャフォールドは両方を正しく生成します。また `package.json#keywords` に `"ampless-plugin"` を加えておくことをお勧めします — npm 検索で ampless プラグインを探す際の慣例です。
+
+runtime がチェックする内容:
+
+| フィールド | 不一致時の動作 |
+|---|---|
+| `apiVersion`（ファクトリ vs マニフェスト） | 起動時に **throws** |
+| `apiVersion`（runtime がサポートするバージョンより新しい） | 起動時に **throws** |
+| `name` | dev で warn |
+| `trustLevel` | dev で warn |
+| `capabilities`（集合比較） | dev で warn |
+
+起動を中断するのは 2 つの `apiVersion` ケースのみです — これは runtime が対応していない ampless API でビルドされたプラグインのロードを防ぎます。その他はすべて開発者向けの警告であり、runtime のブロックではありません。
+
 ---
 
 ## 4. `trust_level` の選び方
@@ -156,7 +294,13 @@ trust level がズレているプラグインは「権限不足で sliently fail
 
 ## 5. 同期サーフェス
 
-**公開 Next.js プロセス** (サイト訪問者のリクエストスレッド) 内で実行されます。AWS に対しては純 (IAM・ネットワーク無し) で、同期実行です。
+**公開 Next.js プロセス** (サイト訪問者のリクエストスレッド) 内で同期実行
+されます。これらの surface はネットワーク I/O を意図して設計していません。
+async result path が無いので `publicHead` 内で `await fetch(...)` すると
+SSR がデッドラインなしでブロックします。ネットワーク呼び出しが必要な副作用
+は `hooks` (trusted Lambda、async) でやってください。公開プロセス内の
+プラグインコードは公開ページ用の IAM ロールで動きます — 特別な AWS 権限は
+ありません。
 
 | サーフェス | 戻り値 | 用途 |
 |---|---|---|
@@ -181,7 +325,14 @@ trust level がズレているプラグインは「権限不足で sliently fail
 
 ## 6. Descriptor リファレンス
 
-`publicHead` と `publicBodyEnd` は **descriptor オブジェクト** を返します。`ReactNode` ではありません。runtime が validation してから React 要素を組み立てます。これが untrusted コードを公開描画パスで動かすための安全境界です。
+`publicHead` と `publicBodyEnd` は **descriptor オブジェクト** を返します。
+`ReactNode` ではありません。runtime が validation (URL scheme denylist /
+attrs allowlist / id dedup) してから React 要素を組み立てます。これは
+プラグインが寄与できる **HTML 出力** の安全境界であって、プラグイン本体の
+コード実行を縛るものではない、という点に注意 — プラグインは普通の
+TypeScript としてサイトと同一の Node プロセスで動きます。descriptor
+パイプラインは、JS sandbox に頼らずに公開ページの面を狭く / 監査可能に
+保つための仕組みです。
 
 ### 共通の variant
 
@@ -319,6 +470,26 @@ export default function schemaJsonldPlugin() {
 
 テーマの `pages/post.tsx` が `ampless.publicBodyForPost(post)` を呼び、返された descriptor を描画します。runtime は自動 escape した body を持つ `<script type="application/ld+json">` 要素をページに挿入します。
 
+### クライアントサイドの DOM 操作はしない
+
+`publicHead` または `publicBodyEnd` から返したインラインスクリプトは、React がページを hydrate する前、HTML のパース中に実行されます。**React が管理するサブツリー内の見える DOM を操作してはいけません** — hydration が走ると React は仮想 DOM と合わないツリーを検出し、`Hydration failed because the server rendered HTML didn't match the client` エラーを投げてサブツリーをゼロから再生成します。挿入したノードは消えてしまいます。
+
+React 19 はさらに、クライアントコンポーネントのレンダー中に出会った `<script>` タグの実行を拒否するため、`document.body.append(myNewElement)` のようなスクリプトはそもそも発火しないことがあります。
+
+**安全なパターン**:
+
+- **グローバル状態 / 非 DOM の副作用**: `window.dataLayer` への push、設定オブジェクトのセット、アナリティクス SDK のインスタンス化。`@ampless/plugin-analytics-ga4`・`@ampless/plugin-gtm`・`@ampless/plugin-plausible` はこの方法を使っています。
+- **外部ウィジェットローダー**: 自前の独立したコンテナを管理するサードパーティスクリプトの読み込み（Crisp・Intercom・Drift など）。ウィジェットの shadow DOM / fixed-position オーバーレイは React のツリーの外にあり、hydration と競合しません。
+- **SSR 専用の descriptor**: `meta` / `link` / `noscript`（`publicBodyEnd` では `iframe` も）を返す — runtime がサーバーサイドで描画するため、最初から React の仮想 DOM の一部になります。
+
+**避けるべきパターン**:
+
+- `document.createElement('div')` + `document.body.append(...)`
+- テーマが描画した要素のクラス / 属性 / テキストコンテンツの変更
+- クライアントサイドで `#post-body` のような要素を読み取って投稿単位の HTML を挿入する — 現在 `publicHead`-for-post に相当するサーフェスはなく、サーバーレンダリング済みのサブツリーをクライアントサイドで書き換えると hydration と競合します
+
+投稿単位の見える出力には、`publicBodyForPost` 経由で JSON-LD を返す（§6 の `PublicPostBodyDescriptor` 参照）か、テーマ自身のテンプレートを使ってください。サーバーサイドでの投稿単位 HTML 注入はロードマップに載っています。
+
 ---
 
 ## 7. 非同期イベントフック
@@ -591,7 +762,82 @@ it('admin が空文字保存した場合は空配列', () => {
 
 ---
 
-## 14. 質問先
+## 14. クイックスタート: `create-ampless` でスキャフォールド
+
+アイデアから動くプラグインへの最速ルートとして、`create-ampless` CLI には `plugin <name>` サブコマンドが用意されています:
+
+```bash
+# サイトローカル: 現在の ampless サイトのルートで実行
+# plugins/<name>/index.ts を生成する
+npx create-ampless@latest plugin my-thing \
+  --trust-level untrusted \
+  --capabilities publicHead,adminSettings
+
+# スタンドアロン npm パッケージ: ./<dir>/ を生成
+# package.json / tsconfig.json / tsup.config.ts / README + .ja /
+# CHANGELOG / .gitignore / src/index.ts + src/index.test.ts を含む
+# 新しいパッケージディレクトリを置きたい場所で実行する
+npx create-ampless@latest plugin @myscope/ampless-plugin-thing \
+  --standalone \
+  --trust-level untrusted \
+  --capabilities publicHead,adminSettings \
+  --description "このプラグインが何をするか"
+```
+
+スタンドアロンスキャフォールドには Phase 5 のクロスチェックに必要なものがすべて含まれます: `package.json#amplessPlugin`、`./package.json` サブパスエクスポート、`packageName` ファクトリフィールド、`ampless-plugin` 検索キーワード、そして `pnpm install && pnpm test && pnpm build` が生成直後にクリーンに通る最小の vitest サンプル。
+
+どちらのモードも、フラグなしの位置引数呼び出し (`npx create-ampless@latest plugin`) で @clack のプロンプト UI を使ったインタラクティブモードに切り替えられます。
+
+### スタンドアロンプラグインの公開
+
+```bash
+cd ampless-plugin-thing
+pnpm install
+pnpm test
+pnpm build
+pnpm publish --access public --tag alpha
+```
+
+スコープ付き名前 (`@scope/...`) には `--access public` が必須です。`--tag alpha` は現在の ampless プレリリースサイクルに合わせています — 安定 major に達したら外してください。
+
+`npm publish` が返った直後に `npm install <pkg>@alpha` で 404 が出ることがあります（CDN とレジストリレプリカの伝播遅延）。その場合は 1〜2 分待ってリトライしてください — `npm view <pkg>@alpha version` がレジストリで見えていることは必要条件ですが十分条件ではありません。
+
+### パッケージの命名
+
+npm の慣例として、スコープと `ampless-plugin-` プレフィックスを除いた短い識別子が `AmplessPlugin.name` になります:
+
+| npm パッケージ | `AmplessPlugin.name` |
+|---|---|
+| `@ampless/plugin-gtm` | `gtm` |
+| `@scope/ampless-plugin-clarity` | `clarity` |
+| `ampless-plugin-readme-toc` | `readme-toc` |
+| `weird-name-no-prefix` | `weird-name-no-prefix` |
+
+スキャフォールドはこのストリッピングを自動で行います。スキャフォールドを使わない場合も同じマッピングで手書きしてください。パッケージの静的マニフェストとファクトリで `name` が一致しない場合はインストール時クロスチェックが警告します。
+
+### サイトローカルの後作業
+
+サイトローカルのスキャフォールド後:
+
+```ts
+// cms.config.ts
+import myThingPlugin from './plugins/my-thing'
+
+export default defineConfig({
+  // ...
+  plugins: [
+    myThingPlugin(),
+  ],
+})
+```
+
+スキャフォールドの最後にこのスニペットが表示されます — `cms.config.ts` にコピーしてプラグインを有効化してください。
+
+`update-ampless` は `plugins/` ディレクトリを決して変更しません（PROTECTED 扱い）。ampless のアップグレードをまたいでも安全に残ります。
+
+---
+
+## 15. 質問先
 
 - アーキテクチャ / 設計の質問 → [`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

package/docs/plugin-author-guide.md

@@ -21,8 +21,62 @@ this page is the hands-on companion.
 
 ---
 
+## 0. Theme vs Plugin Boundary
+
+ampless ships both themes and plugins. Picking the right tool keeps
+your code where future-you (and other site authors) will look for it.
+
+| Want to change... | Use a theme | Use a plugin |
+|---|---|---|
+| Layout, typography, colour, per-route UI | ✓ | |
+| Custom components on home / post / tag pages | ✓ | |
+| Admin-editable settings exposed to non-developers | | ✓ (`adminSettings`) |
+| Background work after content events (RSS, search index, webhooks) | | ✓ (`eventHooks`) |
+| Trusted side effects (S3 writes, external API push) | | ✓ (`writePublicAsset` + `trusted`) |
+| Theme-independent `<head>` / `<body>` injection (analytics, consent) | | ✓ (`publicHead` / `publicBodyEnd`) |
+| Per-post machine-readable metadata (JSON-LD, etc.) | | ✓ (`schema` via `publicBodyForPost`) |
+| Code you want to share across multiple ampless sites | | ✓ (publish as npm package) |
+
+Rule of thumb:
+
+- Theme = **what the page looks like**. Read-only at render time.
+- Plugin = **what happens beyond rendering**: admin-editable config,
+  background processing, theme-agnostic injection, machine-readable
+  metadata, cross-site reusability.
+
+The two boundaries that frequently catch new authors:
+
+- **Storage / DynamoDB / external API writes belong in a plugin**, never
+  a theme. Themes only read.
+- **A feature you want admins to toggle from `/admin/plugins` belongs
+  in a plugin**, even if its visible effect is purely cosmetic. Themes
+  carry their own settings, but those are theme-display settings, not
+  site-operational ones.
+
+Some features genuinely sit at the boundary — see [`docs/architecture/08-plugin-architecture.md`](https://github.com/heavymoons/ampless/blob/main/docs/architecture/08-plugin-architecture.md)
+for the longer discussion.
+
+---
+
 ## 1. What a plugin can do
 
+ampless plugins are written in one of three places — pick the one
+that matches how widely you want the code shared:
+
+| Where | Use when | Lives in |
+|---|---|---|
+| **First-party** | Building on the ampless core for everyone | `packages/plugin-*/` in the ampless monorepo |
+| **Site-local** | Site-specific customisation, no separate publish | `plugins/<name>/` inside your site repo |
+| **External npm package** | Sharing with other sites, ready to `npm publish` | A standalone repo (`@scope/ampless-plugin-foo`) |
+
+All three forms call the same `definePlugin({...})` factory and use the
+same surfaces. The differences are packaging, distribution, and the
+opt-in install-time validation that the static `package.json#amplessPlugin`
+manifest enables (see §3 below).
+
+§14 below has a one-command scaffold (`npx create-ampless plugin <name>`)
+that produces ready-to-use boilerplate for either of the latter two.
+
 An ampless plugin is a TypeScript module that returns an
 `AmplessPlugin` object. It plugs into one or more of the following
 surfaces:
@@ -38,36 +92,72 @@ surfaces:
 | `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.
+A few surfaces don't exist yet — they're reserved for later phases
+and aren't shaped by `definePlugin` today:
+
+- **Arbitrary `ReactNode` injection into pages.** The sync render
+  surfaces (`publicHead`, `publicBodyEnd`, `publicBodyForPost`) only
+  return descriptor variants. The descriptor validator is the safety
+  boundary for what the runtime renders into the page; it isn't a JS
+  sandbox around the plugin itself. (Plugins run as ordinary
+  TypeScript in the same Node process as the rest of the site.)
+- **Network inside the sync render surfaces.** The sync surfaces are
+  shaped for declarative output — they don't take a Promise and there's
+  no async result path, so doing `await fetch(...)` inside `publicHead`
+  blocks SSR with no way to surface a deadline. Trusted Lambdas
+  (`hooks`) are where the runtime expects outbound HTTP. Background
+  work belongs there.
+- **Admin routes / server routes / content fields.** Reserved for
+  Phase 6b.
+- **Secrets.** The `secretSettings` capability is reserved for
+  Phase 6a; nothing in `settings.public` should be a credential.
 
 ---
 
 ## 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:
+The fastest way to create a plugin is to scaffold one:
+
+```bash
+# Site-local (writes plugins/<name>/index.ts in the current ampless site)
+npx create-ampless@latest plugin my-thing
+
+# Standalone npm package (writes ./<name>/ ready for `npm publish`)
+npx create-ampless@latest plugin @myscope/ampless-plugin-my-thing --standalone
+```
+
+§14 covers the full flow. The rest of this section explains what the
+generated files mean, so you can author one by hand if you prefer.
+
+### Site-local
+
+```
+plugins/
+  my-thing/
+    index.ts        # the factory; that's the whole plugin
+```
+
+The site's `package.json` / `tsconfig.json` already cover compilation —
+nothing else needs to ship. Register it from `cms.config.ts` with a
+relative import.
+
+### Standalone npm package
 
 ```
-my-plugin/
+ampless-plugin-my-thing/
   package.json
   tsconfig.json
   tsup.config.ts
+  README.md
+  CHANGELOG.md
   src/
     index.ts
     index.test.ts
 ```
 
 See `packages/plugin-rss/` and `packages/plugin-analytics-ga4/` in
-this repo for working examples.
+this repo for working first-party examples — the standalone scaffold
+mirrors their layout.
 
 The bare-minimum `src/index.ts`:
 
@@ -108,6 +198,7 @@ That's it. Restart `npm run dev`, view source on any page, and the
 ```ts
 interface AmplessPlugin {
   name: string                      // package-like identifier, e.g. 'analytics-ga4'
+  packageName?: string              // npm package name for install-time cross-check
   apiVersion: 1                     // bump only when the contract changes
   trust_level: 'untrusted' | 'trusted' | 'privileged'
   instanceId?: string               // namespace for multi-instance installs
@@ -159,6 +250,87 @@ 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.
 
+### `packageName`
+
+Optional. When set, the runtime resolves
+`<packageName>/package.json` at startup and cross-checks the static
+`amplessPlugin` block there against the factory return value. This
+catches install-time mistakes a plugin author would otherwise only see
+at runtime (or never — capability mismatches don't crash, they just
+quietly skip the surface).
+
+For standalone plugins, set this to the npm package name your
+`package.json#name` declares:
+
+```ts
+return definePlugin({
+  name: 'site-verification',
+  packageName: '@ishinao/ampless-plugin-site-verification',
+  apiVersion: 1,
+  // ...
+})
+```
+
+Site-local plugins don't need it — leave it unset and the cross-check
+is skipped (backward compatible, identical to plugins predating Phase
+5).
+
+### Static manifest in `package.json` (standalone plugins only)
+
+For the cross-check to find the static manifest, two things must be
+true about your published package:
+
+1. `package.json#amplessPlugin` declares the same fields the factory
+   returns:
+
+   ```json
+   "amplessPlugin": {
+     "apiVersion": 1,
+     "name": "site-verification",
+     "trustLevel": "untrusted",
+     "capabilities": ["publicHead", "adminSettings"],
+     "displayName": { "en": "Site verification", "ja": "サイト所有権確認" }
+   }
+   ```
+
+2. `package.json#exports` explicitly exposes `./package.json`:
+
+   ```json
+   "exports": {
+     ".": {
+       "import": "./dist/index.js",
+       "types": "./dist/index.d.ts"
+     },
+     "./package.json": "./package.json"
+   }
+   ```
+
+   Without this, Node's package-exports gating rejects
+   `import.meta.resolve('<pkg>/package.json')` with
+   `ERR_PACKAGE_PATH_NOT_EXPORTED` and the runtime silently skips the
+   cross-check (your plugin still runs; you just don't get the
+   install-time guard).
+
+The `create-ampless plugin --standalone` scaffold ships both correctly.
+Add a `"ampless-plugin"` entry to your `package.json#keywords` while
+you're there — it's the convention used by npm searches surfacing
+ampless plugins.
+
+What the runtime checks:
+
+| Field | Mismatch behaviour |
+|---|---|
+| `apiVersion` (factory vs manifest) | **Throws** at startup |
+| `apiVersion` (newer than runtime supports) | **Throws** at startup |
+| `name` | Warns in dev |
+| `trustLevel` | Warns in dev |
+| `capabilities` (set comparison) | Warns in dev |
+
+The two `apiVersion` cases are the only failure that aborts startup —
+they protect against loading a plugin built for an ampless API the
+runtime can't speak. Everything else is a developer-visible warning,
+not a runtime block.
+
 ---
 
 ## 4. Picking a `trust_level`
@@ -194,8 +366,12 @@ 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.
+request thread) and execute synchronously. They aren't designed to
+do network I/O: there's no async result path, so an `await fetch(...)`
+inside `publicHead` would block SSR with no deadline. Side effects
+that need network calls go in `hooks` (trusted Lambdas, async).
+Public-process plugin code runs with the public-page IAM role — no
+elevated AWS access.
 
 | Surface | Returns | Use case |
 |---|---|---|
@@ -222,9 +398,14 @@ The `ctx` object carries:
 ## 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.
+`ReactNode`. The runtime validates them (URL scheme denylist, attrs
+allowlist, dedup by id) and then builds the React elements itself.
+This is the safety boundary for the **HTML output** a plugin can
+contribute — it bounds what the runtime emits, not what the plugin's
+own code does. Plugins run as ordinary TypeScript in the same Node
+process as the rest of the site; the descriptor pipeline keeps the
+public-page surface narrow and auditable without depending on a JS
+sandbox.
 
 ### Common variants
 
@@ -393,6 +574,49 @@ and renders the returned descriptors. The runtime inserts a
 `<script type="application/ld+json">` element with the auto-escaped
 body into the page.
 
+### Client-side DOM mutation: don't
+
+Inline scripts you return from `publicHead` or `publicBodyEnd` execute
+during HTML parsing, before React hydrates the page. **They must not
+mutate visible DOM inside a React-managed subtree** — when hydration
+runs, React sees a tree that doesn't match its virtual DOM, throws a
+`Hydration failed because the server rendered HTML didn't match the
+client` error, and regenerates the subtree from scratch. Your inserted
+nodes get wiped.
+
+React 19 additionally refuses to execute `<script>` tags it
+encounters while rendering a client component, so a script that did
+something like `document.body.append(myNewElement)` may not even fire.
+
+**Safe patterns**:
+
+- **Global state / non-DOM side effects**: push to `window.dataLayer`,
+  set a config object, instantiate an analytics SDK. This is what
+  `@ampless/plugin-analytics-ga4`, `@ampless/plugin-gtm`, and
+  `@ampless/plugin-plausible` do.
+- **External widget loaders**: load a third-party script that manages
+  its own isolated container (Crisp, Intercom, Drift). The widget's
+  shadow DOM / fixed-position overlay lives outside React's tree and
+  doesn't conflict with hydration.
+- **SSR-only descriptors**: return `meta` / `link` / `noscript` (and,
+  on `publicBodyEnd`, `iframe`) — the runtime renders these
+  server-side and they're part of React's virtual DOM from the start.
+
+**Patterns to avoid**:
+
+- `document.createElement('div')` + `document.body.append(...)`
+- Modifying classes / attributes / text content of elements rendered
+  by the theme
+- Inserting per-post HTML by reading something like `#post-body`
+  client-side — there's no `publicHead`-for-post analogue today, and
+  any client-side rewrite of a server-rendered subtree races against
+  hydration
+
+For visible per-post output, return JSON-LD via `publicBodyForPost`
+(see §6's `PublicPostBodyDescriptor`) or stick with the theme's own
+templates. A future ampless capability for server-side per-post HTML
+injection is on the roadmap.
+
 ---
 
 ## 7. Async event hooks
@@ -757,7 +981,100 @@ Worked examples to crib from:
 
 ---
 
-## 14. Where to ask
+## 14. Quickstart: scaffolding with `create-ampless`
+
+For a fast path from idea to working plugin, the `create-ampless`
+CLI ships a `plugin <name>` subcommand:
+
+```bash
+# Site-local: scaffolds plugins/<name>/index.ts inside the current
+# ampless site. Run from the site repo root.
+npx create-ampless@latest plugin my-thing \
+  --trust-level untrusted \
+  --capabilities publicHead,adminSettings
+
+# Standalone npm package: scaffolds ./<dir>/ with package.json,
+# tsconfig.json, tsup.config.ts, README + .ja, CHANGELOG, .gitignore,
+# and src/index.ts + src/index.test.ts. Run from wherever you want
+# the new package directory to land.
+npx create-ampless@latest plugin @myscope/ampless-plugin-thing \
+  --standalone \
+  --trust-level untrusted \
+  --capabilities publicHead,adminSettings \
+  --description "What this plugin does"
+```
+
+Standalone scaffolds include everything Phase 5's cross-check needs:
+`package.json#amplessPlugin`, the `./package.json` subpath export,
+the `packageName` factory field, the `ampless-plugin` discovery
+keyword, and a minimal vitest sample so `pnpm install && pnpm test &&
+pnpm build` runs clean on the freshly generated directory.
+
+Both modes also accept a positional flag-less invocation (`npx
+create-ampless@latest plugin`) that walks you through the same
+questions interactively via the @clack prompt UI.
+
+### Publishing a standalone plugin
+
+```bash
+cd ampless-plugin-thing
+pnpm install
+pnpm test
+pnpm build
+pnpm publish --access public --tag alpha
+```
+
+`--access public` is mandatory for scoped names (`@scope/...`).
+`--tag alpha` matches the current ampless pre-release cadence — drop
+it once the package reaches a stable major.
+
+There's a publish-to-install lag of "seconds to minutes" before
+`npm install <pkg>@alpha` picks up a fresh publish (CDN + registry
+replica propagation). If `npm install` 404s right after `npm publish`
+returns, wait 1-2 minutes and retry — `npm view <pkg>@alpha version`
+visible in the registry is necessary but sometimes not sufficient.
+
+### Naming the package
+
+By npm convention, scope and the conventional `ampless-plugin-`
+prefix collapse to a short identifier for `AmplessPlugin.name`:
+
+| npm package | `AmplessPlugin.name` |
+|---|---|
+| `@ampless/plugin-gtm` | `gtm` |
+| `@scope/ampless-plugin-clarity` | `clarity` |
+| `ampless-plugin-readme-toc` | `readme-toc` |
+| `weird-name-no-prefix` | `weird-name-no-prefix` |
+
+The scaffold does this stripping automatically. Hand-author the same
+mapping if you skip the scaffold; the install-time cross-check warns
+on a mismatch between the package's static manifest and the factory.
+
+### Site-local follow-up
+
+After a site-local scaffold:
+
+```ts
+// cms.config.ts
+import myThingPlugin from './plugins/my-thing'
+
+export default defineConfig({
+  // ...
+  plugins: [
+    myThingPlugin(),
+  ],
+})
+```
+
+The scaffold prints this snippet at the end of its run — copy it into
+`cms.config.ts` to activate the plugin.
+
+`update-ampless` never touches the `plugins/` directory (it's
+PROTECTED), so the scaffolded code is safe across ampless upgrades.
+
+---
+
+## 15. 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

package/package.json

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