create-ampless 0.2.0-alpha.2 → 0.2.0-alpha.21

package/dist/templates/_shared/RUNBOOK.ja.md

@@ -0,0 +1,150 @@
+> English: [RUNBOOK.md](./RUNBOOK.md)
+> 
+
+# ランブック
+
+ampless で構築したサイトで、ときどき必要になる運用作業の手順集です。毎日やるわけではないけれど、いざ必要になったときに迷わずに進めるためのものです。
+
+日常的な使い方（コマンド、管理画面、テーマ、プラグイン、デプロイなど）は [README.ja.md](./README.ja.md) を参照してください。
+
+## 目次
+
+- [AppSync API キー（自動更新）](#appsync-api-キー自動更新)
+- [よくある運用](#よくある運用)
+  - [ユーザーの昇格 / 降格](#promote--demote-a-user)
+  - [パスワードリセット（管理者上書き）](#reset-a-users-password-admin-override)
+  - [Post テーブルのバックアップから復元](#restore-from-a-post-table-backup)
+  - [失敗したプラグインイベントを確認する](#inspect-failed-plugin-events)
+- [マルチサイト / カスタムドメイン](#multi-site--custom-domains)
+  - [シングルドメイン運用](#single-domain-operation)
+  - [マルチサイト時の注意：SSR キャッシュは強制無効化](#multi-site-mode-caveat-ssr-caching-is-force-disabled)
+  - [カスタムドメインを Amplify Hosting に追加する](#adding-a-custom-domain-to-amplify-hosting)
+
+## AppSync API キー（自動更新）
+
+パブリックブログの読み取り（`listPublishedPosts`、`getPublishedPost`、`listPostsByTag`）は AppSync API キーで保護されています。このキーは `amplify_outputs.json` に含まれているため、**公開サイトを訪問した誰もが確認できる**状態にあります。低信頼度のクレデンシャルとして扱ってください。このキーが持つ権限は上記 3 つのカスタムクエリを呼び出すことのみであり、それらのクエリは `status === 'published'` の行しか返しません。
+
+### なぜ API キーなのか（Identity Pool ゲストロールではなく）？
+
+Amplify Gen 2 の `a.handler.custom` リゾルバーは `allow.guest()` や `allow.authenticated('identityPool')` をサポートしておらず、apiKey / userPool / lambda / group / owner のみが使用可能です。v0.1 では簡潔さを優先して API キーを選択しました。パブリック読み取りを Lambda 関数データソース（`a.handler.function`）に移行することは v0.2 の候補です。
+
+### 自動更新 — ローテーション手順は不要
+
+`api-key-renewer` Lambda（`amplify/functions/api-key-renewer/` を参照）は、毎月 1 日の UTC 03:00 に EventBridge スケジュールで起動します。`AppSync.UpdateApiKey` を呼び出して既存キーの `expires` を「現時点 + 364 日」に延長するため、以下が保証されます：
+
+- キー ID は変化しない
+- `amplify_outputs.json` は引き続き有効
+- Next.js アプリの再ビルドは不要
+- 常に約 334 日以上の残有効期限が維持される
+
+手動で確認または実行したい場合：
+
+```bash
+# 現在の有効期限を確認
+aws appsync list-api-keys \
+  --region <amplify_outputs.json の data.aws_region> \
+  --api-id <amplify_outputs.json の data.url から導出した api-id>
+
+# 手動実行（サンドボックスを長期間停止した後など）
+aws lambda invoke \
+  --function-name $(aws lambda list-functions \
+    --query "Functions[?contains(FunctionName,'api-key-renewer')].FunctionName | [0]" \
+    --output text) \
+  /tmp/out.json && cat /tmp/out.json
+```
+
+### キーの漏洩が疑われる場合
+
+有効期限の延長ではなく、キーの値そのものをローテーションする即時対応を行います：
+
+1. `amplify/data/resource.ts` のコメントを編集して CFN 更新を強制する
+2. `npx ampx sandbox`（サンドボックス）または `npx ampx pipeline-deploy ...`（本番）を実行 — Amplify がキーの値を再生成する
+3. Next.js アプリを再デプロイして SSR が新しい `data.api_key` を参照するようにする
+
+## 一般的な操作
+
+### ユーザーのグループ昇格 / 降格
+
+AWS Cognito コンソールから操作します：
+
+1. User Pool → Users → 対象ユーザーを選択
+2. Group memberships → グループに追加 / グループから削除
+3. ユーザーに一度サインアウトしてサインインし直してもらい、新しいクレームを適用させる
+
+グループの種類： `ampless-admin`（フル CRUD + 運用操作）、`ampless-editor`（コンテンツ CRUD）、`ampless-reader`（将来の REST/MCP API 利用者向けに予約済み）。
+
+### ユーザーパスワードのリセット（管理者による上書き）
+
+ロックアウトされており、メールによる復旧が利用できない場合：
+
+```bash
+aws cognito-idp admin-set-user-password \
+  --user-pool-id <amplify_outputs.json の auth.user_pool_id> \
+  --region <リージョン> \
+  --username <メールアドレス> \
+  --password '<新しいパスワード>' --permanent
+```
+
+`/login` ページにはセルフサービスの「パスワードを忘れた場合」フローもあります。
+
+### Post テーブルのバックアップからの復元
+
+DynamoDB のポイントインタイムリカバリ（PITR）は v0.1 の `defineData` では有効になっていません。AWS コンソール → DynamoDB → Tables → `<投稿テーブル名>` → Backups → Edit PITR から手動で有効化してください。有効化後は `aws dynamodb restore-table-to-point-in-time` で新しいテーブルに復元し、その後アイテムをライブテーブルに移行する作業が必要です。
+
+### 失敗したプラグインイベントの確認
+
+処理に失敗したプロセッサー呼び出しは、`amplify/backend.ts` で作成された共有イベント DLQ（`EventsDlq`）に送られます。SQS コンソールまたは `aws sqs receive-message --queue-url <dlq-url> --max-number-of-messages 10` でメッセージを確認してください。v0.1 には自動アラームがないため、定期的な手動確認を推奨します。あるいは `ApproximateNumberOfMessagesVisible` に CloudWatch アラームを設定してください。
+
+## マルチサイト / カスタムドメイン
+
+ampless は 1 つの Amplify Hosting デプロイメントから複数のサイトを配信できます。各サイトは `siteId` で識別され、`cms.config.ts` 内で 1 つ以上のホスト名に紐づけられます：
+
+```ts
+sites: {
+  blog: {
+    domains: ['blog.example.com', 'www.example.com'],
+    name: 'My Blog',
+    url: 'https://blog.example.com',
+  },
+  docs: {
+    domains: ['docs.example.com'],
+    name: 'Docs',
+    url: 'https://docs.example.com',
+  },
+},
+```
+
+ミドルウェア（`middleware.ts`）が受信リクエストの `Host` を `siteId` にマッピングし、パスを `/_sites/{siteId}/...` に内部リライトします。サブドメインと完全に分離されたドメインはアプリケーション層では等価です — AWS 側の設定のみが異なります。
+
+### シングルドメイン運用
+
+`sites` が未定義または 1 エントリのみの場合、ampless はシングルサイトモード（`siteId='default'`）で動作します。SSR レスポンスはルートごとのキャッシュディレクティブに従います（ルートごとに `Cache-Control: public, s-maxage=...` を指定することで CloudFront キャッシュを利用できます）。
+
+### マルチサイトモードの注意事項：SSR キャッシュの強制無効化
+
+2 つ以上のサイトが設定されている場合、ミドルウェアはすべてのパブリックレスポンスに `Cache-Control: private, no-store` を付加します。これは Amplify Hosting の CloudFront がキャッシュキーに `Host` を含まないため、キャッシュを有効にすると `https://site1/foo` と `https://site2/foo` がエッジでコンテンツを混在させてしまうためです。このトレードオフとして、すべてのパブリック読み取りが Lambda にヒットします。この制約を解消するには、Amplify Hosting から独自管理の CloudFront + Open Next スタックへの移行が必要です（ロードマップ：v1.0 以降）。
+
+### Amplify Hosting へのカスタムドメイン追加
+
+バインドしたいドメインごとに以下を実施します：
+
+1. **Amplify Hosting コンソール** → アプリ → **Domain management** → **Add domain** を選択。
+2. 頂点ドメイン（`example.com`）と接続したいサブドメインを入力します。Amplify が ACM 証明書と CloudFront SAN エントリを自動でプロビジョニングします。
+3. DNS を更新：
+   - **Route 53 / Amplify 管理の DNS プロバイダー**：Amplify が CNAME を作成してくれるので、確認するだけです。
+   - **外部 DNS**（Cloudflare、Squarespace など）：Amplify が表示する CNAME / DNS 検証レコードをコピーします。ACM のメール検証もフォールバックとして使用できます。
+4. **Domain activation** が完了するまで待ちます（通常 15〜60 分。証明書の検証が最も時間がかかります）。
+5. 新しいドメインを `cms.config.ts` の対応する `sites.{id}.domains[]` に追加して再デプロイします：
+   ```bash
+   git add cms.config.ts && git commit -m "feat: add docs.example.com"
+   git push   # Amplify Hosting が自動検出します
+   ```
+
+エンドツーエンドで確認：
+
+```bash
+curl -I https://docs.example.com/                  # 200 とドキュメントサイトの HTML
+curl -sI https://docs.example.com/ | grep -i cache # Cache-Control: private, no-store
+```
+
+リクエストが `404 Site not found` を返す場合、そのホストはいずれの `sites.*.domains[]` にも登録されていません — 設定を修正して再デプロイしてください。

package/dist/templates/_shared/RUNBOOK.md

@@ -1,6 +1,24 @@
+> 日本語版: [RUNBOOK.ja.md](./RUNBOOK.ja.md)
+> 
+
 # Runbook
 
-Operational tasks for an ampless-powered site.
+Step-by-step recipes for occasional operations on an ampless-powered site — the things you don't do every day but want a reliable procedure for when you do.
+
+For day-to-day usage (commands, admin UI tour, themes, plugins, deploying), start with [README.md](./README.md).
+
+## Contents
+
+- [AppSync API key (auto-renewed)](#appsync-api-key-auto-renewed)
+- [Common operations](#common-operations)
+  - [Promote / demote a user](#promote--demote-a-user)
+  - [Reset a user's password (admin override)](#reset-a-users-password-admin-override)
+  - [Restore from a Post-table backup](#restore-from-a-post-table-backup)
+  - [Inspect failed plugin events](#inspect-failed-plugin-events)
+- [Multi-site / custom domains](#multi-site--custom-domains)
+  - [Single domain operation](#single-domain-operation)
+  - [Multi-site mode caveat: SSR caching is force-disabled](#multi-site-mode-caveat-ssr-caching-is-force-disabled)
+  - [Adding a custom domain to Amplify Hosting](#adding-a-custom-domain-to-amplify-hosting)
 
 ## AppSync API key (auto-renewed)
 

package/dist/templates/_shared/amplify/auth/post-confirmation/resource.ts

@@ -3,4 +3,10 @@ import { defineFunction } from '@aws-amplify/backend'
 export const postConfirmation = defineFunction({
   name: 'post-confirmation',
   entry: './handler.ts',
+  // Auth trigger — assign to the auth nested stack so CFN doesn't
+  // place it in a separate `function` stack that ends up in a
+  // circular dependency loop with auth (which references this
+  // function) and storage/data (which auth happens to reach via
+  // cross-stack refs the function adds).
+  resourceGroupName: 'auth',
 })

package/dist/templates/_shared/amplify/backend.custom.ts

@@ -0,0 +1,41 @@
+import type { AmplessBackend } from '@ampless/backend'
+
+// Custom backend extensions for this project.
+//
+// `amplify/backend.ts` calls `customizeBackend(backend)` right after
+// ampless's baseline wiring. Mutate the passed `backend` instance to
+// add Lambda permissions, attach event sources, register custom CDK
+// constructs, etc.
+//
+// This file is NEVER overwritten by `create-ampless upgrade` —
+// `amplify/backend.ts` is, so keep your customizations here.
+//
+// (Function-export rather than side-effect import on purpose: a
+// top-level `import { backend } from './backend.js'` would create an
+// ESM circular dependency, leaving `backend` in its TDZ at evaluation
+// time. The factory pattern sidesteps that.)
+//
+// Example: granting an existing ampless Lambda extra IAM permissions:
+//
+//   import { Effect, PolicyStatement } from 'aws-cdk-lib/aws-iam'
+//
+//   export function customizeBackend(backend: AmplessBackend): void {
+//     backend.processorTrusted.resources.lambda.addToRolePolicy(
+//       new PolicyStatement({
+//         effect: Effect.ALLOW,
+//         actions: ['ses:SendEmail'],
+//         resources: ['*'],
+//       })
+//     )
+//   }
+//
+// Example: adding your own Lambda function — define it in
+// `amplify/functions/<name>/resource.ts`, import it here, and attach
+// it inside `customizeBackend` via `backend.createStack(...)` or by
+// granting it permissions on existing resources.
+//
+// If you don't need any extensions, leave the body empty.
+
+export function customizeBackend(_backend: AmplessBackend): void {
+  // No-op by default.
+}

package/dist/templates/_shared/amplify/backend.ts

@@ -8,13 +8,17 @@ import { eventDispatcher } from './events/dispatcher/resource.js'
 import { processorTrusted } from './events/processor-trusted/resource.js'
 import { processorUntrusted } from './events/processor-untrusted/resource.js'
 import { apiKeyRenewer } from './functions/api-key-renewer/resource.js'
+import { mcpHandler } from './functions/mcp-handler/resource.js'
+import { userAdmin } from './functions/user-admin/resource.js'
+import { customizeBackend } from './backend.custom.js'
 
 // `defineAmplessBackend` provisions auth, data, storage, the event
 // system (DynamoDB Streams → SQS-trusted / SQS-untrusted → trust_level
 // Lambdas), the AppSync API key renewer, and every IAM / CORS /
 // password policy override. Add custom CDK constructs / IAM policies
-// below by mutating the returned `backend` — `defineAmplessBackend`
-// returns the same object Amplify Gen 2's `defineBackend` does.
+// in `amplify/backend.custom.ts` by mutating the `backend` instance —
+// `defineAmplessBackend` returns the same object Amplify Gen 2's
+// `defineBackend` does.
 const backend = defineAmplessBackend({
   auth,
   data,
@@ -24,6 +28,12 @@ const backend = defineAmplessBackend({
   processorTrusted,
   processorUntrusted,
   apiKeyRenewer,
+  mcpHandler,
+  userAdmin,
 })
 
+// Run user-defined customizations after baseline wiring. `backend.custom.ts`
+// is never overwritten by `create-ampless upgrade`.
+customizeBackend(backend)
+
 export default backend

package/dist/templates/_shared/amplify/data/resource.custom.ts

@@ -0,0 +1,33 @@
+// Custom data schema models for this project.
+//
+// `amplify/data/resource.ts` calls `customSchemaModels(a)` and spreads
+// the result alongside ampless's built-in models in the same
+// `a.schema({...})` call, which is the only way Amplify Gen 2's
+// `ClientSchema<typeof schema>` inference picks up extra models.
+//
+// This file is NEVER overwritten by `create-ampless upgrade` —
+// `amplify/data/resource.ts` is, so keep your custom models here.
+//
+// Example:
+//
+//   export function customSchemaModels(a: any) {
+//     return {
+//       Bookmark: a
+//         .model({
+//           siteId: a.string().required(),
+//           bookmarkId: a.id().required(),
+//           url: a.string().required(),
+//           title: a.string(),
+//         })
+//         .identifier(['siteId', 'bookmarkId'])
+//         .authorization((allow: any) => [allow.groups(['ampless-admin', 'ampless-editor'])]),
+//     }
+//   }
+//
+// `a` is the Amplify Gen 2 schema builder; see Amplify Data docs for
+// the full DSL. Return an empty object if no customizations are needed.
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export function customSchemaModels(_a: any): Record<string, unknown> {
+  return {}
+}

package/dist/templates/_shared/amplify/data/resource.ts

@@ -1,26 +1,34 @@
+import { fileURLToPath } from 'node:url'
+import { dirname, resolve } from 'node:path'
 import { a, defineData, type ClientSchema } from '@aws-amplify/backend'
 import { amplessSchemaModels, defaultAuthorizationModes } from '@ampless/backend'
+import { userAdmin } from '../functions/user-admin/resource.js'
+import { customSchemaModels } from './resource.custom.js'
+
+// AppSync's `a.handler.custom({ entry })` paths are resolved by CDK
+// relative to the file that called `a.handler.custom`. When the call
+// originates inside `@ampless/backend` (via amplessSchemaModels), the
+// CDK synth tries to resolve `./list-published-posts.js` relative to
+// `node_modules/@ampless/backend/dist/index.js` and fails with
+// `UnresolvedEntryPathError`. Anchor the resolver paths at THIS file's
+// directory so the result is unambiguous.
+const __dirname = dirname(fileURLToPath(import.meta.url))
 
 // Ampless's built-in models (Post / Page / Media / Taxonomy / PostTag /
 // KvStore) plus the three public-read custom queries
 // (listPublishedPosts / getPublishedPost / listPostsByTag).
 //
-// Add project-specific models alongside the spread:
-//
-//   const schema = a.schema({
-//     ...amplessSchemaModels(a),
-//     MyCustomModel: a
-//       .model({ siteId: a.string().required(), foo: a.string() })
-//       .identifier(['siteId', 'foo'])
-//       .authorization((allow) => [allow.groups(['ampless-admin'])]),
-//   })
-//
-// The three AppSync JS resolvers (`*.js` in this directory) stay
-// user-owned — AppSync resolves `entry: './...'` paths at synth time
-// relative to this file. If you relocate them, pass new paths via
-// `amplessSchemaModels(a, { resolverPaths: { ... } })`.
+// Add project-specific models in `amplify/data/resource.custom.ts` —
+// that file is never overwritten by `create-ampless upgrade`.
+const resolverPaths = {
+  listPublishedPosts: resolve(__dirname, 'list-published-posts.js'),
+  getPublishedPost: resolve(__dirname, 'get-published-post.js'),
+  listPostsByTag: resolve(__dirname, 'list-posts-by-tag.js'),
+}
+
 const schema = a.schema({
-  ...amplessSchemaModels(a),
+  ...amplessSchemaModels(a, { resolverPaths, userAdminFunction: userAdmin }),
+  ...customSchemaModels(a),
 })
 
 export type Schema = ClientSchema<typeof schema>

package/dist/templates/_shared/amplify/events/processor-untrusted/resource.ts

@@ -6,4 +6,8 @@ export const processorUntrusted = defineFunction({
   // Untrusted plugins do pure JS work; modest memory.
   memoryMB: 256,
   timeoutSeconds: 30,
+  // Pin to the data stack so all event-system Lambdas live together
+  // (dispatcher / processor-trusted are also `data`) and the function
+  // stack doesn't bridge data ↔ storage ↔ auth in a CFN cycle.
+  resourceGroupName: 'data',
 })

package/dist/templates/_shared/amplify/functions/mcp-handler/handler.ts

@@ -0,0 +1 @@
+export { handler } from '@ampless/backend/functions/mcp-handler'

package/dist/templates/_shared/amplify/functions/mcp-handler/resource.ts

@@ -0,0 +1,11 @@
+import { defineFunction } from '@aws-amplify/backend'
+
+export const mcpHandler = defineFunction({
+  name: 'mcp-handler',
+  entry: './handler.ts',
+  // Co-locate with the data stack so the function has the KvStore
+  // table ARN available without cross-stack references at synth time.
+  resourceGroupName: 'data',
+  memoryMB: 512,
+  timeoutSeconds: 30,
+})

package/dist/templates/_shared/amplify/functions/user-admin/handler.ts

@@ -0,0 +1,4 @@
+// Re-exported from @ampless/backend so the package can ship Lambda
+// handler updates via `npm update`. Amplify's esbuild follows this
+// import and bundles the real handler into the Lambda artifact.
+export { handler } from '@ampless/backend/auth/user-admin'

package/dist/templates/_shared/amplify/functions/user-admin/resource.ts

@@ -0,0 +1,12 @@
+import { defineFunction } from '@aws-amplify/backend'
+
+// `resourceGroupName: 'data'` co-locates this Lambda with the AppSync
+// stack. Required because ampless wires userAdmin as a custom GraphQL
+// resolver (data → function) while api-key-renewer reads graphqlApi
+// (function → data); leaving userAdmin in the default `function` stack
+// turns those two arrows into a CloudFormation circular dependency.
+export const userAdmin = defineFunction({
+  name: 'user-admin',
+  entry: './handler.ts',
+  resourceGroupName: 'data',
+})

package/dist/templates/_shared/amplify.yml

@@ -0,0 +1,18 @@
+version: 1
+frontend:
+  phases:
+    preBuild:
+      commands:
+        - npm install
+    build:
+      commands:
+        - npx ampx pipeline-deploy --branch $AWS_BRANCH --app-id $AWS_APP_ID
+        - npm run build
+  artifacts:
+    baseDirectory: .next
+    files:
+      - '**/*'
+  cache:
+    paths:
+      - node_modules/**/*
+      - .next/cache/**/*

package/dist/templates/_shared/app/(admin)/admin/mcp-tokens/page.tsx

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

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

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

package/dist/templates/_shared/app/globals.css

@@ -1,4 +1,17 @@
 @import 'tailwindcss';
+
+/*
+ * Tailwind v4 doesn't scan `node_modules/` by default. The admin UI
+ * (`@ampless/admin`) and runtime UI bits (`@ampless/runtime`) ship
+ * compiled JS that uses Tailwind utility classes; without these
+ * explicit sources, every utility used only inside those packages
+ * (e.g. the admin sidebar's `flex`, `fixed`, `md:sticky`, ...) gets
+ * tree-shaken out of the final CSS, and the admin layout falls back
+ * to browser defaults — sidebar overlaps main content, etc.
+ */
+@source '../node_modules/@ampless/admin/dist';
+@source '../node_modules/@ampless/runtime/dist';
+
 @plugin '@tailwindcss/typography';
 /* DADS theme plugin from Digital Agency. Loaded globally so the
  * `templates/dads/` theme can use DADS-conformant color variables
@@ -36,6 +49,31 @@
   --radius-sm: calc(var(--radius) - 4px);
 }
 
+/*
+ * Color scheme:
+ *
+ * - `:root { color-scheme: light dark }` opts the page into both modes
+ *   and asks the browser to pick based on the visitor's
+ *   `prefers-color-scheme` setting.
+ * - `html[data-color-scheme='light' | 'dark']` lets the site admin pin
+ *   one mode regardless of system preference. The attribute is written
+ *   by `app/layout.tsx` from the per-site setting
+ *   (`theme.colorScheme`, default `'auto'` = no attribute).
+ * - Token values below (and in each theme's `tokens.css`) use the CSS
+ *   `light-dark(L, D)` function so a single declaration covers both
+ *   modes — the active `color-scheme` selects between L and D at
+ *   paint time.
+ */
+:root {
+  color-scheme: light dark;
+}
+html[data-color-scheme='light'] {
+  color-scheme: light;
+}
+html[data-color-scheme='dark'] {
+  color-scheme: dark;
+}
+
 /*
  * Default tokens — used as fallback when no theme's `[data-theme=...]`
  * selector matches (e.g. body has no data-theme attribute, or admin
@@ -45,49 +83,27 @@
  * `<body data-theme="...">` attribute makes the scoped selector match.
  */
 :root {
-  --background: oklch(1 0 0);
-  --foreground: oklch(0.145 0 0);
-  --card: oklch(1 0 0);
-  --card-foreground: oklch(0.145 0 0);
-  --primary: oklch(0.205 0 0);
-  --primary-foreground: oklch(0.985 0 0);
-  --secondary: oklch(0.97 0 0);
-  --secondary-foreground: oklch(0.205 0 0);
-  --muted: oklch(0.97 0 0);
-  --muted-foreground: oklch(0.556 0 0);
-  --accent: oklch(0.97 0 0);
-  --accent-foreground: oklch(0.205 0 0);
-  --destructive: oklch(0.577 0.245 27.325);
-  --destructive-foreground: oklch(0.985 0 0);
-  --border: oklch(0.922 0 0);
-  --input: oklch(0.922 0 0);
-  --ring: oklch(0.708 0 0);
+  --background: light-dark(oklch(1 0 0), oklch(0.145 0 0));
+  --foreground: light-dark(oklch(0.145 0 0), oklch(0.985 0 0));
+  --card: light-dark(oklch(1 0 0), oklch(0.145 0 0));
+  --card-foreground: light-dark(oklch(0.145 0 0), oklch(0.985 0 0));
+  --primary: light-dark(oklch(0.205 0 0), oklch(0.985 0 0));
+  --primary-foreground: light-dark(oklch(0.985 0 0), oklch(0.205 0 0));
+  --secondary: light-dark(oklch(0.97 0 0), oklch(0.269 0 0));
+  --secondary-foreground: light-dark(oklch(0.205 0 0), oklch(0.985 0 0));
+  --muted: light-dark(oklch(0.97 0 0), oklch(0.269 0 0));
+  --muted-foreground: light-dark(oklch(0.556 0 0), oklch(0.708 0 0));
+  --accent: light-dark(oklch(0.97 0 0), oklch(0.269 0 0));
+  --accent-foreground: light-dark(oklch(0.205 0 0), oklch(0.985 0 0));
+  --destructive: light-dark(oklch(0.577 0.245 27.325), oklch(0.396 0.141 25.723));
+  --destructive-foreground: light-dark(oklch(0.985 0 0), oklch(0.985 0 0));
+  --border: light-dark(oklch(0.922 0 0), oklch(0.269 0 0));
+  --input: light-dark(oklch(0.922 0 0), oklch(0.269 0 0));
+  --ring: light-dark(oklch(0.708 0 0), oklch(0.439 0 0));
   --radius: 0.5rem;
   --ampless-body-font: system-ui, -apple-system, sans-serif;
 }
 
-@media (prefers-color-scheme: dark) {
-  :root {
-    --background: oklch(0.145 0 0);
-    --foreground: oklch(0.985 0 0);
-    --card: oklch(0.145 0 0);
-    --card-foreground: oklch(0.985 0 0);
-    --primary: oklch(0.985 0 0);
-    --primary-foreground: oklch(0.205 0 0);
-    --secondary: oklch(0.269 0 0);
-    --secondary-foreground: oklch(0.985 0 0);
-    --muted: oklch(0.269 0 0);
-    --muted-foreground: oklch(0.708 0 0);
-    --accent: oklch(0.269 0 0);
-    --accent-foreground: oklch(0.985 0 0);
-    --destructive: oklch(0.396 0.141 25.723);
-    --destructive-foreground: oklch(0.985 0 0);
-    --border: oklch(0.269 0 0);
-    --input: oklch(0.269 0 0);
-    --ring: oklch(0.439 0 0);
-  }
-}
-
 body {
   font-family: var(--ampless-body-font, system-ui, -apple-system, sans-serif);
   background: var(--background);

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

@@ -1,6 +1,7 @@
 import type { Metadata } from 'next'
 import { headers } from 'next/headers'
 import { DEFAULT_SITE_ID } from 'ampless'
+import { validateColorScheme } from '@ampless/runtime'
 import { Providers } from './providers'
 import { siteMetadata } from '@/lib/seo'
 import { loadThemeConfig, renderThemeCss } from '@/lib/theme-config'
@@ -25,8 +26,28 @@ export default async function RootLayout({ children }: { children: React.ReactNo
   const themeCss = renderThemeCss(theme.cssVars)
   const locale = getLocale()
   const dict = getDictionary(locale)
+  // `data-color-scheme` pins the visitor to light or dark regardless
+  // of their system `prefers-color-scheme`. `'auto'` (the default)
+  // means we don't emit the attribute at all, so `globals.css`'s
+  // `:root { color-scheme: light dark }` lets the browser follow the
+  // system setting. Themes use `light-dark()` in their tokens.css so a
+  // single declaration covers both modes; the active `color-scheme`
+  // selects which value is rendered.
+  //
+  // The admin's theme-settings iframe preview passes the unsaved
+  // selection via `?previewColorScheme=<mode>`, which middleware
+  // forwards as `x-preview-color-scheme`. When that header is present
+  // it overrides the stored site setting so the preview updates live.
+  const previewHeader = h.get('x-preview-color-scheme')
+  const effectiveColorScheme = previewHeader
+    ? validateColorScheme(previewHeader)
+    : theme.colorScheme
+  const htmlProps: { lang: string; 'data-color-scheme'?: 'light' | 'dark' } = { lang: locale }
+  if (effectiveColorScheme !== 'auto') {
+    htmlProps['data-color-scheme'] = effectiveColorScheme
+  }
   return (
-    <html lang={locale}>
+    <html {...htmlProps}>
       <head>
         {/* Inline `:root` overrides come AFTER globals.css so they win
             against the static defaults. Validated values only — see

package/dist/templates/_shared/app/site/[siteId]/[...path]/route.ts

@@ -0,0 +1,17 @@
+import { ampless } from '@/lib/ampless'
+import { createStaticRouteHandler } from '@ampless/runtime/routes'
+
+// Catch-all handler for `format: 'static'` post bundles. Lives here
+// instead of under a dedicated `/static/` prefix so the published URL
+// stays a clean `/<slug>/…`, matching how a developer would host a
+// hand-written landing page locally. The runtime handler enforces
+// `format === 'static'` and 404s for any other post format reaching
+// this route.
+//
+// Routing precedence: Next.js prefers the more specific
+// `[siteId]/[slug]/page.tsx` for single-segment URLs, so the regular
+// theme post dispatcher keeps handling normal posts. This catch-all
+// only fires for multi-segment requests (e.g. `/promo/index.html`,
+// `/promo/assets/style.css`).
+export const dynamic = 'force-dynamic'
+export const GET = createStaticRouteHandler(ampless)

package/dist/templates/_shared/lib/admin.ts

@@ -7,13 +7,14 @@
 // `amplify_outputs.json` and `cms.config` into a single `Admin`
 // instance.
 //
-// NOTE: We intentionally do NOT pass an `ampless` instance to
-// createAdmin. That would import `lib/ampless.ts`, which imports
-// `themes-registry`, which (via theme pages → `lib/i18n.ts`) imports
-// back to this file — a circular chain that crashes with a TDZ
-// ReferenceError on `ampless` at module init. `createAdmin` builds
-// its own internal Ampless when omitted, which is functionally
-// equivalent for admin's needs.
+// NOTE: we pass `ampless` as a thunk (not the resolved instance) so we
+// don't have a static `import './ampless'` at the top of this file.
+// A static import would form the cycle
+//   `lib/admin.ts → lib/ampless.ts → themes-registry → themes → lib/i18n.ts → lib/admin.ts`
+// and crash with a TDZ ReferenceError on `ampless` at module init.
+// The thunk uses dynamic `import()` so `lib/ampless.ts` only loads on
+// the first `loadSiteSettings` / `loadThemeConfig` call (request
+// time), by which point every module has finished initialising.
 
 import outputs from '../amplify_outputs.json'
 import cmsConfig from '@/cms.config'
@@ -22,6 +23,7 @@ import { createAdmin } from '@ampless/admin'
 export const admin = createAdmin({
   outputs,
   cmsConfig,
+  ampless: async () => (await import('./ampless')).ampless,
   locale: (cmsConfig as { locale?: string }).locale ?? 'en',
 })