create-ampless 1.0.0-alpha.71 → 1.0.0-alpha.76

package/dist/index.js

@@ -1755,6 +1755,7 @@ var AMPLESS_PACKAGES = /* @__PURE__ */ new Set([
   "@ampless/runtime",
   "@ampless/plugin-seo",
   "@ampless/plugin-rss",
+  "@ampless/plugin-schema-jsonld",
   "@ampless/plugin-webhook",
   "@ampless/plugin-og-image",
   "@ampless/plugin-analytics-ga4",
@@ -1781,13 +1782,32 @@ var PROTECTED_PATTERNS = [
   /^\.amplify(\/|$)/,
   /^amplify_outputs\.json$/,
   /^next-env\.d\.ts$/,
+  // `tsconfig.json` is auto-managed by Next.js during `next build` /
+  // `next dev` — it rewrites `jsx: "preserve"` → `"react-jsx"` for
+  // the React automatic runtime and appends `.next/dev/types/**/*.ts`
+  // to `include`. Treating the file as `replace` here would overwrite
+  // those mutations on every `update-ampless`, only for Next.js to
+  // re-apply them on the next build — a churn cycle that produces a
+  // dirty diff after every upgrade. Protect the file; users hand-
+  // merge new compiler options in the rare case the template
+  // tsconfig changes meaningfully.
+  /^tsconfig\.json$/,
   /^tsconfig\.tsbuildinfo$/,
   /^pnpm-lock\.yaml$/,
   /^package-lock\.json$/,
   // Anything under themes/ is handled by syncThemes; the file-walk
   // classifier must not double-process it.
   /^themes(\/|$)/,
-  /^themes-registry\.ts$/
+  /^themes-registry\.ts$/,
+  // `plugins/` is the site-local plugin directory (user-owned, mirrors
+  // the `themes/my-*` convention for user-customised themes). The
+  // initial scaffold seeds a README into this directory; everything
+  // afterwards is the user's territory. We never overwrite or delete
+  // files here — even the seeded README is frozen at scaffold time,
+  // because plugin authors will sometimes edit it to document the
+  // site's own conventions. The kept-up-to-date "how to write a
+  // plugin" doc lives in `packages/ampless/docs/plugin-author-guide.md`.
+  /^plugins(\/|$)/
 ];
 var SEED_IF_MISSING_PATTERN = /\.custom\.ts$/;
 var TEXT_EXTENSIONS2 = /* @__PURE__ */ new Set([

package/dist/templates/_shared/cms.config.ts

@@ -1,6 +1,7 @@
 import { defineConfig } from 'ampless'
 import seoPlugin from '@ampless/plugin-seo'
 import rssPlugin from '@ampless/plugin-rss'
+// import schemaJsonLdPlugin from '@ampless/plugin-schema-jsonld'
 // import analyticsGa4Plugin from '@ampless/plugin-analytics-ga4'
 // import gtmPlugin from '@ampless/plugin-gtm'
 // import plausiblePlugin from '@ampless/plugin-plausible'
@@ -95,6 +96,17 @@ export default defineConfig({
     //   domain: '', // 'example.com' to enable
     // }),
     //
+    // JSON-LD structured data (Schema.org). Injects <script type="application/ld+json">
+    // into post pages for Article / BlogPosting markup. articleType, authorName and
+    // publisherName fall back to the site name when left empty.
+    //
+    // schemaJsonLdPlugin({
+    //   articleType: 'Article', // 'Article' | 'BlogPosting' | 'NewsArticle'
+    //   authorName: '', // empty falls back to site.name
+    //   publisherName: '', // empty falls back to site.name
+    //   publisherLogo: '', // optional absolute URL to publisher logo
+    // }),
+    //
     // Per-post OG images: SNS crawlers hit `/og/<slug>` and we render
     // a JSX card → PNG via Next.js `ImageResponse`. Requires at least one
     // font — ship a .ttf from your CDN or `/public` directory.

package/dist/templates/_shared/components/tag-list.tsx

@@ -3,14 +3,18 @@ import Link from 'next/link'
 interface TagListProps {
   tags?: string[] | null
   className?: string
+  /** Cap the number of tags shown; the rest collapse into a "+N" indicator. */
+  max?: number
 }
 
 // Renders post tags as chip-style links to /tag/[tag]. Pure-server, no JS.
-export function TagList({ tags, className }: TagListProps) {
+export function TagList({ tags, className, max }: TagListProps) {
   if (!tags?.length) return null
+  const shown = max != null ? tags.slice(0, max) : tags
+  const overflow = tags.length - shown.length
   return (
     <ul className={`flex flex-wrap gap-2 ${className ?? ''}`}>
-      {tags.map((tag) => (
+      {shown.map((tag) => (
         <li key={tag}>
           <Link
             href={`/tag/${encodeURIComponent(tag)}`}
@@ -20,6 +24,9 @@ export function TagList({ tags, className }: TagListProps) {
           </Link>
         </li>
       ))}
+      {overflow > 0 && (
+        <li className="inline-block px-2 py-0.5 text-xs text-muted-foreground">+{overflow}</li>
+      )}
     </ul>
   )
 }

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

@@ -9,7 +9,7 @@
 
 # ampless プラグインの書き方
 
-このガイドは、初めての `definePlugin()` 呼び出しから admin 編集可能な設定パネル、そして npm 公開に至るまで、ampless プラグインを ship するために必要な手順を一通りカバーします。Phase 1 + Phase 2 の機能を網羅 — descriptor ベースの `<head>` / `<body>` 注入、非同期イベントフック、admin 管理の `settings.public` 値です。
+このガイドは、初めての `definePlugin()` 呼び出しから admin 編集可能な設定パネル、そして npm 公開に至るまで、ampless プラグインを ship するために必要な手順を一通りカバーします。Phase 1〜4 の機能を網羅 — descriptor ベースの `<head>` / `<body>` / 投稿単位 body 注入、非同期イベントフック、admin 管理の `settings.public` 値です。
 
 設計の経緯と背景は [`docs/architecture/08-plugin-architecture.md`](https://github.com/heavymoons/ampless/blob/main/docs/architecture/08-plugin-architecture.md) に集約。本ページはその実装ハンドブック側です。
 
@@ -25,6 +25,7 @@ ampless プラグインは `AmplessPlugin` オブジェクトを返す TypeScrip
 | `siteMetadata(site)` | root layout の `generateMetadata()` | 同期 | 既存 |
 | `publicHead(ctx)` | root layout の `<head>` | 同期 (async layout から呼ばれる) | 1 |
 | `publicBodyEnd(ctx)` | root layout の `<body>` 末尾 | 同期 | 1 |
+| `publicBodyForPost(post, ctx)` | テーマの post ページテンプレート（投稿単位） | 同期 | 4 |
 | `ogImage` | `/og/[slug]` ルート | リクエスト時、公開 Lambda 内 | 既存 |
 | `hooks` | trust_level に応じた processor Lambda | 非同期、SQS イベントで起動 | 既存 |
 | `settings.public` | `/admin/plugins` フォーム | 宣言的なマニフェスト | 2 |
@@ -102,6 +103,7 @@ interface AmplessPlugin {
   siteMetadata?(site): PluginMetadata
   publicHead?(ctx): readonly PublicHeadDescriptor[]
   publicBodyEnd?(ctx): readonly PublicBodyDescriptor[]
+  publicBodyForPost?(post: Post, ctx): readonly PublicPostBodyDescriptor[]
   ogImage?: OgImageConfig
   settings?: { public?: readonly PluginSettingField[] }
 }
@@ -162,6 +164,7 @@ trust level がズレているプラグインは「権限不足で sliently fail
 | `siteMetadata(site)` | `PluginMetadata` | サイト全体の `<title>` / favicon / RSS `<link rel="alternate">` |
 | `publicHead(ctx)` | `PublicHeadDescriptor[]` | 解析ローダー、フォント、jsonld、hreflang |
 | `publicBodyEnd(ctx)` | `PublicBodyDescriptor[]` | GTM no-script フレーム、チャットウィジェット、末尾スニペット |
+| `publicBodyForPost(post, ctx)` | `PublicPostBodyDescriptor[]` | 投稿単位の body 注入 — JSON-LD 構造化データ。テーマの post ページテンプレートが render する |
 
 `ctx` オブジェクトの中身:
 
@@ -202,6 +205,15 @@ trust level がズレているプラグインは「権限不足で sliently fail
   strategy: 'afterInteractive',
 }
 
+// inline script — JSON-LD variant (publicHead / publicBodyEnd / publicBodyForPost で使用可能)
+// runtime が body を自動 escape するので、生の JSON 文字列を返せばよい
+{
+  type: 'inlineScript',
+  id: 'schema-article',
+  scriptType: 'application/ld+json',
+  body: JSON.stringify({ '@context': 'https://schema.org', '@type': 'Article', ... }),
+}
+
 // Meta / link / noscript
 { type: 'meta', name: 'theme-color', content: '#fff' }
 { type: 'meta', property: 'og:image', content: 'https://…' }
@@ -223,6 +235,36 @@ trust level がズレているプラグインは「権限不足で sliently fail
 }
 ```
 
+### `PublicPostBodyDescriptor`（Phase 4）
+
+`publicBodyForPost` は `PublicPostBodyDescriptor[]` を返します。これは `inlineScript` の制限サブセットで、`scriptType` が必須かつ `'application/ld+json'` のみ有効です：
+
+```ts
+// publicBodyForPost で返せる唯一の形:
+{
+  type: 'inlineScript',
+  id: 'schema-article',
+  scriptType: 'application/ld+json',   // 必須 — これ以外は drop + warn
+  body: JSON.stringify({ '@context': 'https://schema.org', '@type': 'Article', ... }),
+}
+```
+
+`meta` / `link` を除いている理由：投稿単位のメタデータは Next.js `generateMetadata()` 経由の `metadata()` サーフェスが担い、フレームワークの deduplication・streaming と統合されている。`publicBodyForPost` は `generateMetadata` が生成できない構造化データ（`<script type="application/ld+json">`）のためだけに存在する。
+
+### JSON-LD 自動 escape
+
+`scriptType === 'application/ld+json'` のとき、runtime は描画前に **`body` 文字列を自動 escape** する — `<` → `<`、`>` → `>`、`&` → `&`、U+2028 → ` `、U+2029 → ` `。この処理は `inlineScript` を受け付ける 3 つのサーフェス（`publicHead` / `publicBodyEnd` / `publicBodyForPost`）すべてで行われる。プラグイン作者は生の JSON 文字列を返せばよく、自前で escape しなくてよい。
+
+サポート外の `scriptType` を持つ descriptor は **console warning 付きで drop** される。
+
+### サーフェス別 scriptType ルール
+
+| サーフェス | `scriptType` |
+|---|---|
+| `publicHead` | `undefined`（デフォルト JS）または `'application/ld+json'` |
+| `publicBodyEnd` | `publicHead` と同じ |
+| `publicBodyForPost` | `'application/ld+json'` **必須**。他の値（省略含む）は drop + warn |
+
 ### Validation ルール
 
 - **URL scheme allowlist**: `http`、`https`、または相対パス。`javascript:`、`data:`、`vbscript:`、`blob:`、`file:` は要素描画前に拒否されます
@@ -244,6 +286,39 @@ trust level がズレているプラグインは「権限不足で sliently fail
 
 `cms.config.plugins` の順序は集約後も保たれます。
 
+### `publicBodyForPost` の使用例（Phase 4）
+
+`schema` capability を宣言してサーフェスを実装します：
+
+```typescript
+import { definePlugin } from 'ampless'
+
+export default function schemaJsonldPlugin() {
+  return definePlugin({
+    name: 'schema-jsonld',
+    apiVersion: 1,
+    trust_level: 'untrusted',
+    capabilities: ['schema'],
+    publicBodyForPost(post, ctx) {
+      return [{
+        type: 'inlineScript',
+        id: 'schema-article',
+        scriptType: 'application/ld+json',
+        body: JSON.stringify({
+          '@context': 'https://schema.org',
+          '@type': 'Article',
+          headline: post.title,
+          url: `${ctx.site.url}/${post.slug}`,
+          datePublished: post.publishedAt,
+        }),
+      }]
+    },
+  })
+}
+```
+
+テーマの `pages/post.tsx` が `ampless.publicBodyForPost(post)` を呼び、返された descriptor を描画します。runtime は自動 escape した body を持つ `<script type="application/ld+json">` 要素をページに挿入します。
+
 ---
 
 ## 7. 非同期イベントフック
@@ -493,6 +568,7 @@ it('admin が空文字保存した場合は空配列', () => {
 - [`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` ルートレンダラ
+- [`packages/plugin-schema-jsonld`](https://github.com/heavymoons/ampless/tree/main/packages/plugin-schema-jsonld) — `publicBodyForPost` + `schema` capability、投稿単位 Article JSON-LD。（Phase 4）
 
 ---
 
@@ -510,6 +586,8 @@ it('admin が空文字保存した場合は空配列', () => {
 - **`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 が変わってもそのフィールドだけ反映されなくなります
+- **`publicBodyForPost` で `scriptType: 'application/ld+json'` を省略**。`publicBodyForPost` が返す descriptor で `scriptType` を省略するか他の値を指定すると、production では silent に drop、dev では warn されます。このサーフェスで有効なのは `'application/ld+json'` だけです
+- **`schema` capability と `publicBodyForPost` の不一致**。`capabilities: ['schema']` を宣言して `publicBodyForPost` を未実装（またはその逆）にすると起動時に warning が出ます。宣言と実装は同期させてください
 
 ---
 

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

@@ -12,8 +12,8 @@
 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
+Phase 1–4 surfaces — descriptor-based `<head>` / `<body>` /
+per-post 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);
@@ -33,6 +33,7 @@ surfaces:
 | `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 |
+| `publicBodyForPost(post, ctx)` | theme post page template (per-post) | sync | 4 |
 | `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 |
@@ -117,6 +118,7 @@ interface AmplessPlugin {
   siteMetadata?(site): PluginMetadata
   publicHead?(ctx): readonly PublicHeadDescriptor[]
   publicBodyEnd?(ctx): readonly PublicBodyDescriptor[]
+  publicBodyForPost?(post: Post, ctx): readonly PublicPostBodyDescriptor[]
   ogImage?: OgImageConfig
   settings?: { public?: readonly PluginSettingField[] }
 }
@@ -201,6 +203,7 @@ network — and execute synchronously.
 | `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 |
+| `publicBodyForPost(post, ctx)` | `PublicPostBodyDescriptor[]` | Per-post body injection — JSON-LD structured data; rendered by the theme's post page template |
 
 The `ctx` object carries:
 
@@ -246,6 +249,15 @@ untrusted code in the public render path.
   strategy: 'afterInteractive',
 }
 
+// Inline script — JSON-LD variant (valid in publicHead, publicBodyEnd, publicBodyForPost)
+// The runtime auto-escapes the body; return raw JSON, not pre-escaped.
+{
+  type: 'inlineScript',
+  id: 'schema-article',
+  scriptType: 'application/ld+json',
+  body: JSON.stringify({ '@context': 'https://schema.org', '@type': 'Article', ... }),
+}
+
 // Meta / link / noscript
 { type: 'meta', name: 'theme-color', content: '#fff' }
 { type: 'meta', property: 'og:image', content: 'https://…' }
@@ -267,6 +279,49 @@ untrusted code in the public render path.
 }
 ```
 
+### `PublicPostBodyDescriptor` (Phase 4)
+
+`publicBodyForPost` returns `PublicPostBodyDescriptor[]`. This is a
+restricted subset of `inlineScript` where `scriptType` is required
+and must be `'application/ld+json'`:
+
+```ts
+// The only valid form for publicBodyForPost:
+{
+  type: 'inlineScript',
+  id: 'schema-article',
+  scriptType: 'application/ld+json',   // required — only value accepted
+  body: JSON.stringify({ '@context': 'https://schema.org', '@type': 'Article', ... }),
+}
+```
+
+Why `meta` and `link` are excluded: per-post metadata is already
+handled by Next.js `generateMetadata()` via the `metadata()` surface,
+which integrates with the framework's deduplication and streaming
+behaviour. `publicBodyForPost` exists solely for the structured data
+use-case (`<script type="application/ld+json">`) that `generateMetadata`
+cannot produce.
+
+### JSON-LD auto-escape
+
+When `scriptType === 'application/ld+json'`, the runtime **automatically
+escapes the `body` string** before rendering — `<` → `<`,
+`>` → `>`, `&` → `&`, U+2028 → `
`, U+2029 → `
`.
+This applies across all three surfaces that accept `inlineScript`
+(`publicHead`, `publicBodyEnd`, `publicBodyForPost`). Return the raw
+JSON string; do not pre-escape it.
+
+Descriptors with an unsupported `scriptType` value are **dropped with
+a console warning** and never rendered.
+
+### Surface-dependent `scriptType` rules
+
+| Surface | `scriptType` |
+|---|---|
+| `publicHead` | `undefined` (default JS) or `'application/ld+json'` |
+| `publicBodyEnd` | same as `publicHead` |
+| `publicBodyForPost` | `'application/ld+json'` **required**; any other value (including omitted) is dropped + warned |
+
 ### Validation rules
 
 - **URL scheme allowlist**: `http`, `https`, or relative paths.
@@ -302,6 +357,42 @@ interpolates that fragment directly:
 `cms.config.plugins` iteration order is preserved across the
 collected list.
 
+### `publicBodyForPost` example (Phase 4)
+
+Declare the `schema` capability and implement the surface:
+
+```typescript
+import { definePlugin } from 'ampless'
+
+export default function schemaJsonldPlugin() {
+  return definePlugin({
+    name: 'schema-jsonld',
+    apiVersion: 1,
+    trust_level: 'untrusted',
+    capabilities: ['schema'],
+    publicBodyForPost(post, ctx) {
+      return [{
+        type: 'inlineScript',
+        id: 'schema-article',
+        scriptType: 'application/ld+json',
+        body: JSON.stringify({
+          '@context': 'https://schema.org',
+          '@type': 'Article',
+          headline: post.title,
+          url: `${ctx.site.url}/${post.slug}`,
+          datePublished: post.publishedAt,
+        }),
+      }]
+    },
+  })
+}
+```
+
+The theme's `pages/post.tsx` calls `ampless.publicBodyForPost(post)`
+and renders the returned descriptors. The runtime inserts a
+`<script type="application/ld+json">` element with the auto-escaped
+body into the page.
+
 ---
 
 ## 7. Async event hooks
@@ -619,6 +710,7 @@ Worked examples to crib from:
 - [`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.
+- [`packages/plugin-schema-jsonld`](https://github.com/heavymoons/ampless/tree/main/packages/plugin-schema-jsonld) — `publicBodyForPost` + `schema` capability; per-post Article JSON-LD. (Phase 4)
 
 ---
 
@@ -654,6 +746,14 @@ Worked examples to crib from:
   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.
+- **`publicBodyForPost` without `scriptType: 'application/ld+json'`.** Descriptors
+  returned from `publicBodyForPost` that omit `scriptType` or use any
+  other value are silently dropped in production and warned in dev.
+  Only `scriptType: 'application/ld+json'` is valid in that surface.
+- **`schema` capability + `publicBodyForPost` mismatch.** Declaring
+  `capabilities: ['schema']` without implementing `publicBodyForPost`
+  (or the reverse) prints a startup warning. Keep the declaration and
+  implementation in sync.
 
 ---
 

package/dist/templates/_shared/package.json

@@ -25,18 +25,19 @@
     "@tiptap/pm": "^3.23.6",
     "@tiptap/react": "^3.23.6",
     "@tiptap/starter-kit": "^3.23.6",
-    "@ampless/plugin-analytics-ga4": "^0.2.0-alpha.3",
-    "@ampless/plugin-gtm": "^0.1.1-alpha.2",
-    "@ampless/plugin-og-image": "^0.2.0-alpha.20",
-    "@ampless/plugin-plausible": "^0.1.1-alpha.2",
-    "@ampless/plugin-rss": "^0.2.0-alpha.20",
-    "@ampless/plugin-seo": "^0.2.0-alpha.20",
-    "@ampless/plugin-webhook": "^0.2.0-alpha.20",
-    "@ampless/admin": "^1.0.0-alpha.46",
-    "@ampless/backend": "^1.0.0-alpha.37",
-    "@ampless/runtime": "^1.0.0-alpha.26",
+    "@ampless/plugin-analytics-ga4": "^0.2.0-alpha.4",
+    "@ampless/plugin-gtm": "^0.1.1-alpha.3",
+    "@ampless/plugin-og-image": "^0.2.0-alpha.21",
+    "@ampless/plugin-plausible": "^0.1.1-alpha.3",
+    "@ampless/plugin-rss": "^0.2.0-alpha.21",
+    "@ampless/plugin-schema-jsonld": "^0.1.1-alpha.0",
+    "@ampless/plugin-seo": "^0.2.0-alpha.21",
+    "@ampless/plugin-webhook": "^0.2.0-alpha.21",
+    "@ampless/admin": "^1.0.0-alpha.48",
+    "@ampless/backend": "^1.0.0-alpha.38",
+    "@ampless/runtime": "^1.0.0-alpha.27",
     "@digital-go-jp/tailwind-theme-plugin": "^0.3.4",
-    "ampless": "^1.0.0-alpha.20",
+    "ampless": "^1.0.0-alpha.21",
     "aws-amplify": "^6.17.0",
     "class-variance-authority": "^0.7.1",
     "clsx": "^2.1.1",

package/dist/templates/_shared/plugins/README.ja.md

@@ -0,0 +1,111 @@
+> English: [README.md](./README.md)
+
+# サイトローカルプラグイン
+
+このディレクトリは **このサイト専用のプラグイン置き場**。別 npm
+パッケージとして publish したくない小さなカスタマイズを書く場所。
+
+`update-ampless` はこのディレクトリのファイルに一切触らない。ここに置いた
+ものは消えない、上書きされない。
+
+## いつ使うか
+
+サイト固有の機能で、以下に当てはまるときに使う:
+
+- プラグイン surface (`publicHead` / `publicBodyEnd` / `metadata` / `eventHooks` 等) が必要
+- このサイト限定の用途 (一度きりのフッタークレジット、サイト特有の JSON-LD 拡張、まだ汎用化したくない analytics スニペット等)
+- 別パッケージとして version 上げて publish するのは大袈裟
+
+複数サイトで使いたくなったら、独立 npm パッケージに切り出す (Phase 5 で
+`npx create-ampless plugin --standalone` が来る予定。今は手でコピーで OK)。
+
+## 最小例
+
+`plugins/footer-credit/index.ts`:
+
+```typescript
+import { definePlugin, type AmplessPlugin } from 'ampless'
+
+export interface FooterCreditOptions {
+  instanceId?: string
+}
+
+export default function footerCreditPlugin(
+  options: FooterCreditOptions = {}
+): AmplessPlugin {
+  const instanceId = options.instanceId ?? 'footer-credit'
+  return definePlugin({
+    name: 'footer-credit',
+    instanceId,
+    apiVersion: 1,
+    trust_level: 'untrusted',
+    displayName: { en: 'Footer credit', ja: 'フッタークレジット' },
+    capabilities: ['publicBody', 'adminSettings'],
+    settings: {
+      public: [
+        {
+          type: 'text',
+          key: 'html',
+          label: { en: 'Snippet', ja: 'スニペット' },
+          default: '',
+        },
+      ],
+    },
+    publicBodyEnd(ctx) {
+      const html = (ctx.setting<string>('html') ?? '').trim()
+      if (!html) return []
+      return [{ type: 'noscript', id: `footer-credit-${instanceId}`, html }]
+    },
+  })
+}
+```
+
+`cms.config.ts` で register:
+
+```typescript
+import footerCreditPlugin from './plugins/footer-credit'
+
+export default defineConfig({
+  // ...
+  plugins: [
+    // ...既存 plugin...
+    footerCreditPlugin(),
+  ],
+})
+```
+
+これだけ。`next dev` 再起動 → `/admin/plugins` でスニペットを設定すれば、
+すべての公開ページの `</body>` 直前にレンダされる。
+
+## 宣言できる surface
+
+プラグインは `definePlugin({...})` で組み立てるただのオブジェクト。型は
+`node_modules/ampless/dist/plugin.d.ts` を見るか、[プラグイン作者ガイド][guide]
+の散文で。
+
+現状 active な capability:
+
+| capability | 用途 |
+|---|---|
+| `publicHead` | `<head>` に site-wide で挿入される descriptor |
+| `publicBody` | `</body>` 直前に site-wide で挿入される descriptor |
+| `metadata` | post ごとの Next.js Metadata 拡張 |
+| `eventHooks` | trusted/untrusted の背景ハンドラ (content lifecycle / media event 等) |
+| `adminSettings` | `settings.public[]` で宣言する admin 編集可能な設定 |
+| `writePublicAsset` | trusted plugin が `public/plugins/<instanceId>/...` に書き込み |
+| `schema` | post ごとの JSON-LD を `publicBodyForPost` 経由で (テーマ側で `ampless.publicBodyForPost(post)` を呼ぶ前提) |
+
+[guide]: https://github.com/heavymoons/ampless/blob/main/packages/ampless/docs/plugin-author-guide.md
+
+## TypeScript 設定
+
+`tsconfig.json` の `**/*.ts` include glob でこのディレクトリも自動的に
+カバーされている。`import x from './plugins/foo'` も
+`import x from '@/plugins/foo'` も追加設定なしで動く。
+
+## `update-ampless` はどうなるか
+
+何もしない。`plugins/` は upgrade ツールの protected list に入っているので、
+ここに置いたファイルは上書きも削除もされない。代償として **この README
+も更新されない** — プラグイン API に大きな変更があるときは、本家リポジトリの
+[プラグイン作者ガイド][guide] で最新版を確認すること。

package/dist/templates/_shared/plugins/README.md

@@ -0,0 +1,113 @@
+> 日本語版: [README.ja.md](./README.ja.md)
+
+# Site-local plugins
+
+This directory is for **plugins that belong only to this site** — small
+customizations you don't want to publish as a separate npm package.
+
+`update-ampless` never touches files in this directory, so anything you
+add here is yours to keep.
+
+## When to use a local plugin
+
+Reach for a local plugin when you want a site-specific feature that:
+
+- needs the plugin surface (`publicHead` / `publicBodyEnd` / `metadata` / `eventHooks` / etc.)
+- is specific to this site (a one-off footer credit, a custom JSON-LD enrichment, an analytics snippet you're not yet ready to ship as a reusable package)
+- you'd rather not version-bump or republish to iterate on
+
+When the plugin grows useful for more than one site, lift it into its
+own npm package (see `npx create-ampless plugin --standalone` once it
+ships in Phase 5; for now you can copy it out by hand).
+
+## Minimal example
+
+`plugins/footer-credit/index.ts`:
+
+```typescript
+import { definePlugin, type AmplessPlugin } from 'ampless'
+
+export interface FooterCreditOptions {
+  instanceId?: string
+}
+
+export default function footerCreditPlugin(
+  options: FooterCreditOptions = {}
+): AmplessPlugin {
+  const instanceId = options.instanceId ?? 'footer-credit'
+  return definePlugin({
+    name: 'footer-credit',
+    instanceId,
+    apiVersion: 1,
+    trust_level: 'untrusted',
+    displayName: { en: 'Footer credit', ja: 'フッタークレジット' },
+    capabilities: ['publicBody', 'adminSettings'],
+    settings: {
+      public: [
+        {
+          type: 'text',
+          key: 'html',
+          label: { en: 'Snippet', ja: 'スニペット' },
+          default: '',
+        },
+      ],
+    },
+    publicBodyEnd(ctx) {
+      const html = (ctx.setting<string>('html') ?? '').trim()
+      if (!html) return []
+      return [{ type: 'noscript', id: `footer-credit-${instanceId}`, html }]
+    },
+  })
+}
+```
+
+Register it in `cms.config.ts`:
+
+```typescript
+import footerCreditPlugin from './plugins/footer-credit'
+
+export default defineConfig({
+  // ...
+  plugins: [
+    // ...existing plugins...
+    footerCreditPlugin(),
+  ],
+})
+```
+
+That's it. Restart `next dev` and visit `/admin/plugins` to configure
+the snippet, then any public page renders it before `</body>`.
+
+## What you can declare
+
+A plugin is just an object built with `definePlugin({...})`. The full
+shape lives in `node_modules/ampless/dist/plugin.d.ts` (or [the plugin
+author guide][guide] if you prefer prose).
+
+Capabilities currently active:
+
+| capability | purpose |
+|---|---|
+| `publicHead` | descriptors rendered in `<head>` site-wide |
+| `publicBody` | descriptors rendered before `</body>` site-wide |
+| `metadata` | per-post Next.js Metadata contributions |
+| `eventHooks` | trusted/untrusted background handlers (content lifecycle, media events, ...) |
+| `adminSettings` | admin-editable settings declared via `settings.public[]` |
+| `writePublicAsset` | trusted plugins can write namespaced files under `public/plugins/<instanceId>/...` |
+| `schema` | per-post JSON-LD via `publicBodyForPost` (theme template must call `ampless.publicBodyForPost(post)`) |
+
+[guide]: https://github.com/heavymoons/ampless/blob/main/packages/ampless/docs/plugin-author-guide.md
+
+## What about TypeScript?
+
+`tsconfig.json` already covers this directory through its `**/*.ts`
+include glob. Both `import x from './plugins/foo'` and
+`import x from '@/plugins/foo'` work; no extra setup needed.
+
+## What `update-ampless` does
+
+Nothing. `plugins/` is in the upgrade tool's protected list, so files
+here are never overwritten or deleted on upgrade. The flip side is that
+this README does not get refreshed either — when ampless ships
+significant changes to the plugin API, check the [plugin author guide][guide]
+in the canonical repo for the up-to-date version.

package/dist/templates/blog/pages/home.tsx

@@ -81,7 +81,7 @@ export default async function BlogHome(_: ThemeRouteContext) {
                   )}
                   {post.excerpt && <p className="mt-2 text-gray-700">{post.excerpt}</p>}
                 </Link>
-                <TagList tags={post.tags} className="mt-3" />
+                <TagList tags={post.tags} className="mt-3" max={3} />
               </li>
             ))}
           </ul>

package/dist/templates/blog/pages/post.tsx

@@ -12,6 +12,16 @@ import { SiteFooter } from '@/components/site-chrome/site-footer'
 
 type PostCtx = ThemeRouteContext<{ slug: string }>
 
+function buildPostUrl(siteUrl: string, slug: string) {
+  return new URL(`/${slug}`, siteUrl).toString()
+}
+
+function buildXShareUrl(articleUrl: string, title: string, excerpt?: string | null) {
+  const text = [`"${title}"`, excerpt].filter(Boolean).join('\n\n')
+  const params = new URLSearchParams({ url: articleUrl, text })
+  return `https://x.com/intent/tweet?${params.toString()}`
+}
+
 export async function generatePostMetadata({ params }: PostCtx): Promise<Metadata> {
   const { slug } = await params
   const post = await ampless.getPublishedPost(slug)
@@ -28,6 +38,8 @@ export default async function BlogPost({ params }: PostCtx) {
   ])
   if (!post) notFound()
 
+  const postBody = await ampless.publicBodyForPost(post)
+
   const defaultLightbox = settings.media.imageDisplay === 'lightbox'
   const maxWidth = settings.media.imageMaxWidth ?? '100%'
   const proseStyle: React.CSSProperties = {
@@ -36,6 +48,8 @@ export default async function BlogPost({ params }: PostCtx) {
   const showHeader =
     parseLinkList(theme.values.headerNav).length > 0 || !!theme.values.logoUrl?.trim()
   const showFooter = parseLinkList(theme.values.footerLinks).length > 0
+  const articleUrl = buildPostUrl(settings.site.url, post.slug)
+  const xShareUrl = buildXShareUrl(articleUrl, post.title, post.excerpt)
 
   return (
     <>
@@ -63,6 +77,8 @@ export default async function BlogPost({ params }: PostCtx) {
             )}
           </header>
 
+          {postBody}
+
           <div
             id="post-body"
             className="prose prose-neutral dark:prose-invert max-w-none [&_img]:max-w-[var(--ampless-img-max-width)] [&_img]:mx-auto"
@@ -71,6 +87,16 @@ export default async function BlogPost({ params }: PostCtx) {
           />
 
           <TagList tags={post.tags} className="mt-8 border-t pt-6" />
+
+          <footer className="mt-6 flex flex-wrap items-center gap-x-6 gap-y-2 text-sm text-gray-500">
+            <a href={articleUrl} className="hover:text-foreground hover:underline">{admin.t('public.permalink')}</a>
+            <a href={xShareUrl} target="_blank" rel="noopener noreferrer" className="inline-flex items-center gap-1.5 hover:text-foreground hover:underline">
+              <svg aria-hidden="true" viewBox="0 0 24 24" className="h-3.5 w-3.5" fill="currentColor">
+                <path d="M13.8 10.4 21 2h-1.7l-6.2 7.3L8.1 2H2.3l7.6 11.1L2.3 22h1.7l6.7-7.8 5.4 7.8h5.8l-8.1-11.6Zm-2.4 2.8-.8-1.1L4.5 3.3h2.8l4.9 7.1.8 1.1 6.4 9.2h-2.8l-5.2-7.5Z" />
+              </svg>
+              {admin.t('public.shareOnX')}
+            </a>
+          </footer>
         </article>
 
         <LightboxBinder scopeSelector="#post-body" defaultLightbox={defaultLightbox} />

package/dist/templates/corporate/pages/post.tsx

@@ -28,6 +28,8 @@ export default async function CorporatePost({ params }: PostCtx) {
   ])
   if (!post) notFound()
 
+  const postBody = await ampless.publicBodyForPost(post)
+
   const defaultLightbox = settings.media.imageDisplay === 'lightbox'
   const maxWidth = settings.media.imageMaxWidth ?? '100%'
   const proseStyle: React.CSSProperties = {
@@ -64,6 +66,8 @@ export default async function CorporatePost({ params }: PostCtx) {
             )}
           </header>
 
+          {postBody}
+
           <div
             id="post-body"
             className="prose prose-neutral dark:prose-invert max-w-none [&_img]:max-w-[var(--ampless-img-max-width)] [&_img]:mx-auto"

package/dist/templates/dads/pages/post.tsx

@@ -28,6 +28,8 @@ export default async function DadsPost({ params }: PostCtx) {
   ])
   if (!post) notFound()
 
+  const postBody = await ampless.publicBodyForPost(post)
+
   const defaultLightbox = settings.media.imageDisplay === 'lightbox'
   const maxWidth = settings.media.imageMaxWidth ?? '100%'
   const proseStyle: React.CSSProperties = {
@@ -69,6 +71,8 @@ export default async function DadsPost({ params }: PostCtx) {
             )}
           </header>
 
+          {postBody}
+
           <div
             id="post-body"
             className="prose prose-neutral dark:prose-invert max-w-none [&_a]:text-[var(--primary)] [&_a]:underline-offset-4 [&_img]:max-w-[var(--ampless-img-max-width)] [&_img]:mx-auto"

package/dist/templates/docs/pages/post.tsx

@@ -32,6 +32,8 @@ export default async function DocsPost({ params }: PostCtx) {
   ])
   if (!post) notFound()
 
+  const postBody = await ampless.publicBodyForPost(post)
+
   const defaultLightbox = settings.media.imageDisplay === 'lightbox'
   const maxWidth = settings.media.imageMaxWidth ?? '100%'
   const proseStyle: React.CSSProperties = {
@@ -66,6 +68,8 @@ export default async function DocsPost({ params }: PostCtx) {
               )}
             </header>
 
+            {postBody}
+
             <div
               id="post-body"
               className="prose prose-neutral dark:prose-invert max-w-none [&_img]:max-w-[var(--ampless-img-max-width)] [&_img]:mx-auto"

package/dist/templates/landing/pages/post.tsx

@@ -28,6 +28,8 @@ export default async function LandingPost({ params }: PostCtx) {
   ])
   if (!post) notFound()
 
+  const postBody = await ampless.publicBodyForPost(post)
+
   const defaultLightbox = settings.media.imageDisplay === 'lightbox'
   const maxWidth = settings.media.imageMaxWidth ?? '100%'
   const proseStyle: React.CSSProperties = {
@@ -66,6 +68,8 @@ export default async function LandingPost({ params }: PostCtx) {
             )}
           </header>
 
+          {postBody}
+
           <div
             id="post-body"
             className="prose prose-neutral dark:prose-invert max-w-none [&_img]:max-w-[var(--ampless-img-max-width)] [&_img]:mx-auto"

package/dist/templates/minimal/pages/post.tsx

@@ -25,6 +25,8 @@ export default async function MinimalPost({ params }: PostCtx) {
   ])
   if (!post) notFound()
 
+  const postBody = await ampless.publicBodyForPost(post)
+
   const defaultLightbox = settings.media.imageDisplay === 'lightbox'
   const maxWidth = settings.media.imageMaxWidth ?? '100%'
   const proseStyle: React.CSSProperties = {
@@ -47,6 +49,8 @@ export default async function MinimalPost({ params }: PostCtx) {
           )}
         </header>
 
+        {postBody}
+
         <div
           id="post-body"
           className="prose prose-neutral dark:prose-invert max-w-none [&_img]:max-w-[var(--ampless-img-max-width)] [&_img]:mx-auto"

package/package.json

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