create-ampless 0.2.0-alpha.0

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

@@ -0,0 +1,30 @@
+import { a, defineData, type ClientSchema } from '@aws-amplify/backend'
+import { amplessSchemaModels, defaultAuthorizationModes } from '@ampless/backend'
+
+// 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: { ... } })`.
+const schema = a.schema({
+  ...amplessSchemaModels(a),
+})
+
+export type Schema = ClientSchema<typeof schema>
+export const data = defineData({
+  schema,
+  authorizationModes: defaultAuthorizationModes,
+})

package/dist/templates/_shared/amplify/events/dispatcher/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/events/dispatcher'

package/dist/templates/_shared/amplify/events/dispatcher/resource.ts

@@ -0,0 +1,12 @@
+import { defineFunction } from '@aws-amplify/backend'
+
+export const eventDispatcher = defineFunction({
+  name: 'event-dispatcher',
+  entry: './handler.ts',
+  // Co-locate with the data stack — the function reads the Post table's
+  // DynamoDB Stream, so being in the same stack avoids a CloudFormation
+  // circular dependency between data, function, and auth.
+  resourceGroupName: 'data',
+  memoryMB: 256,
+  timeoutSeconds: 30,
+})

package/dist/templates/_shared/amplify/events/processor-trusted/handler.ts

@@ -0,0 +1,12 @@
+import config from '../../../cms.config'
+import { createProcessorTrustedHandler } from '@ampless/backend/events/processor-trusted'
+
+// Plugins + site come from the user-side `cms.config`. The factory
+// filters down to `trust_level === 'trusted'` plugins, wires the
+// runtime context (listPublishedPosts / writePublicAsset), and runs
+// the built-in site-settings cache rebuild on
+// `site.settings.updated` events.
+export const handler = createProcessorTrustedHandler({
+  plugins: config.plugins,
+  site: config.site,
+})

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

@@ -0,0 +1,14 @@
+import { defineFunction } from '@aws-amplify/backend'
+
+export const processorTrusted = defineFunction({
+  name: 'processor-trusted',
+  entry: './handler.ts',
+  // Co-locate with data — this Lambda reads the Post table to assemble
+  // sitemap/RSS, so we keep the dependency intra-stack and avoid a
+  // function → data → auth → function cycle.
+  resourceGroupName: 'data',
+  // Higher than dispatcher because plugins (sitemap/RSS) load all
+  // published posts and serialize XML.
+  memoryMB: 512,
+  timeoutSeconds: 60,
+})

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

@@ -0,0 +1,10 @@
+import config from '../../../cms.config'
+import { createProcessorUntrustedHandler } from '@ampless/backend/events/processor-untrusted'
+
+// Untrusted plugins get a runtime context with NO AWS-touching
+// capabilities — listPublishedPosts / writePublicAsset throw. The
+// factory filters `trust_level === 'untrusted'` from cms.config.
+export const handler = createProcessorUntrustedHandler({
+  plugins: config.plugins,
+  site: config.site,
+})

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

@@ -0,0 +1,9 @@
+import { defineFunction } from '@aws-amplify/backend'
+
+export const processorUntrusted = defineFunction({
+  name: 'processor-untrusted',
+  entry: './handler.ts',
+  // Untrusted plugins do pure JS work; modest memory.
+  memoryMB: 256,
+  timeoutSeconds: 30,
+})

package/dist/templates/_shared/amplify/functions/api-key-renewer/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/functions/api-key-renewer'

package/dist/templates/_shared/amplify/functions/api-key-renewer/resource.ts

@@ -0,0 +1,12 @@
+import { defineFunction } from '@aws-amplify/backend'
+
+export const apiKeyRenewer = defineFunction({
+  name: 'api-key-renewer',
+  entry: './handler.ts',
+  // Co-locate with the data stack — the function reads/updates the
+  // AppSync API's API key, so being in the same stack avoids a CFN
+  // dependency cycle between data, function, and auth.
+  resourceGroupName: 'data',
+  memoryMB: 256,
+  timeoutSeconds: 30,
+})

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

@@ -0,0 +1,7 @@
+import { defineAmplessStorage } from '@ampless/backend'
+
+// Provisions the ampless media + plugins bucket with guest read on
+// `public/*` and admin/editor write on the matched prefixes. CORS and
+// the bucket-level public-access policy are applied by
+// defineAmplessBackend.
+export const storage = defineAmplessStorage()

package/dist/templates/_shared/app/(admin)/admin/layout.tsx

@@ -0,0 +1,4 @@
+import { admin } from '@/lib/admin'
+import { createAdminLayout } from '@ampless/admin/pages'
+
+export default createAdminLayout(admin)

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

@@ -0,0 +1,4 @@
+import { admin } from '@/lib/admin'
+import { createMediaPage } from '@ampless/admin/pages'
+
+export default createMediaPage(admin)

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

@@ -0,0 +1,4 @@
+import { admin } from '@/lib/admin'
+import { createAdminDashboardPage } from '@ampless/admin/pages'
+
+export default createAdminDashboardPage(admin)

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

@@ -0,0 +1,4 @@
+import { admin } from '@/lib/admin'
+import { createEditPostPage } from '@ampless/admin/pages'
+
+export default createEditPostPage(admin)

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

@@ -0,0 +1,4 @@
+import { admin } from '@/lib/admin'
+import { createNewPostPage } from '@ampless/admin/pages'
+
+export default createNewPostPage(admin)

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

@@ -0,0 +1,4 @@
+import { admin } from '@/lib/admin'
+import { createPostsListPage } from '@ampless/admin/pages'
+
+export default createPostsListPage(admin)

package/dist/templates/_shared/app/(admin)/admin/sites/[siteId]/page.tsx

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

package/dist/templates/_shared/app/(admin)/admin/sites/[siteId]/theme/page.tsx

@@ -0,0 +1,6 @@
+import { admin } from '@/lib/admin'
+import { createSiteThemePage } from '@ampless/admin/pages'
+import { themeList } from '@/themes-registry'
+
+export const dynamic = 'force-dynamic'
+export default createSiteThemePage(admin, themeList)

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

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

package/dist/templates/_shared/app/api/media/[...path]/route.ts

@@ -0,0 +1,5 @@
+import { admin } from '@/lib/admin'
+import { createMediaProxyRoute } from '@ampless/admin/api'
+
+export const { GET } = createMediaProxyRoute(admin)
+export const runtime = 'nodejs'

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

@@ -0,0 +1,114 @@
+@import 'tailwindcss';
+@plugin '@tailwindcss/typography';
+/* DADS theme plugin from Digital Agency. Loaded globally so the
+ * `templates/dads/` theme can use DADS-conformant color variables
+ * (`--color-blue-900` etc., the canonical solidBlue). Other themes
+ * don't reference DADS-specific classes, so the plugin's tokens
+ * sit unused for them — small CSS overhead, no behavior change. */
+@plugin '@digital-go-jp/tailwind-theme-plugin';
+
+/*
+ * Tailwind v4 inline theme: every `--color-*` and `--radius-*` token
+ * the framework knows about reads from a CSS variable, so theme
+ * tokens.css files can override them at runtime by changing the right
+ * data-theme block.
+ */
+@theme inline {
+  --color-background: var(--background);
+  --color-foreground: var(--foreground);
+  --color-card: var(--card);
+  --color-card-foreground: var(--card-foreground);
+  --color-primary: var(--primary);
+  --color-primary-foreground: var(--primary-foreground);
+  --color-secondary: var(--secondary);
+  --color-secondary-foreground: var(--secondary-foreground);
+  --color-muted: var(--muted);
+  --color-muted-foreground: var(--muted-foreground);
+  --color-accent: var(--accent);
+  --color-accent-foreground: var(--accent-foreground);
+  --color-destructive: var(--destructive);
+  --color-destructive-foreground: var(--destructive-foreground);
+  --color-border: var(--border);
+  --color-input: var(--input);
+  --color-ring: var(--ring);
+  --radius-lg: var(--radius);
+  --radius-md: calc(var(--radius) - 2px);
+  --radius-sm: calc(var(--radius) - 4px);
+}
+
+/*
+ * Default tokens — used as fallback when no theme's `[data-theme=...]`
+ * selector matches (e.g. body has no data-theme attribute, or admin
+ * pages that aren't theme-scoped). Each installed theme ships its own
+ * `themes/<name>/tokens.css` overriding these under
+ * `[data-theme='<name>']`. The active theme's tokens win because the
+ * `<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);
+  --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);
+  color: var(--foreground);
+}
+
+* {
+  border-color: var(--border);
+}
+
+/*
+  Tighten list spacing inside `.prose`. The Typography plugin's default
+  treats every <li> as roughly a paragraph's worth of vertical rhythm,
+  and tiptap wraps each list item in <p> — so we get double margins
+  and the list looks like loose paragraphs rather than a list.
+*/
+.prose :where(li):not(:where([class~='not-prose'] *)) {
+  margin-top: 0.25em;
+  margin-bottom: 0.25em;
+}
+.prose :where(li > p):not(:where([class~='not-prose'] *)) {
+  margin-top: 0;
+  margin-bottom: 0;
+}

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

@@ -0,0 +1,48 @@
+import type { Metadata } from 'next'
+import { headers } from 'next/headers'
+import { DEFAULT_SITE_ID } from 'ampless'
+import { Providers } from './providers'
+import { siteMetadata } from '@/lib/seo'
+import { loadThemeConfig, renderThemeCss } from '@/lib/theme-config'
+import { getLocale, getDictionary } from '@/lib/i18n'
+import { I18nProvider } from '@/components/i18n-provider'
+import './globals.css'
+
+// Resolve metadata per site at request time. The middleware sets
+// `x-site-id` so we can pick the right merged settings; falls back to
+// DEFAULT_SITE_ID for admin / API routes that don't go through the
+// public middleware path.
+export async function generateMetadata(): Promise<Metadata> {
+  const h = await headers()
+  const siteId = h.get('x-site-id') ?? DEFAULT_SITE_ID
+  return siteMetadata(siteId)
+}
+
+export default async function RootLayout({ children }: { children: React.ReactNode }) {
+  const h = await headers()
+  const siteId = h.get('x-site-id') ?? DEFAULT_SITE_ID
+  const theme = await loadThemeConfig(siteId)
+  const themeCss = renderThemeCss(theme.cssVars)
+  const locale = getLocale()
+  const dict = getDictionary(locale)
+  return (
+    <html lang={locale}>
+      <head>
+        {/* Inline `:root` overrides come AFTER globals.css so they win
+            against the static defaults. Validated values only — see
+            ampless `validateThemeValue`. */}
+        {themeCss && <style dangerouslySetInnerHTML={{ __html: themeCss }} />}
+      </head>
+      {/* `data-theme` selects which theme's `tokens.css` block matches.
+          The active theme is resolved from `theme.active` site setting,
+          falling back to DEFAULT_THEME — see `resolveActiveTheme`. */}
+      <body className="min-h-screen" data-theme={theme.activeTheme}>
+        <Providers>
+          <I18nProvider locale={locale} dict={dict}>
+            {children}
+          </I18nProvider>
+        </Providers>
+      </body>
+    </html>
+  )
+}

package/dist/templates/_shared/app/login/page.tsx

@@ -0,0 +1,4 @@
+import { admin } from '@/lib/admin'
+import { createLoginPage } from '@ampless/admin/pages'
+
+export default createLoginPage(admin)

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

@@ -0,0 +1,13 @@
+'use client'
+
+import { useEffect } from 'react'
+import '@/lib/amplify'
+import '@/lib/posts-provider'
+import '@/lib/kv-provider'
+
+export function Providers({ children }: { children: React.ReactNode }) {
+  useEffect(() => {
+    // Amplify is configured via the side-effect import above
+  }, [])
+  return <>{children}</>
+}

package/dist/templates/_shared/app/site/[siteId]/[slug]/page.tsx

@@ -0,0 +1,10 @@
+import { ampless } from '@/lib/ampless'
+import {
+  createThemePostDispatcher,
+  createThemePostMetadata,
+} from '@ampless/runtime/dispatchers'
+
+export const dynamic = 'force-dynamic'
+
+export const generateMetadata = createThemePostMetadata(ampless)
+export default createThemePostDispatcher(ampless)

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

@@ -0,0 +1,5 @@
+import { ampless } from '@/lib/ampless'
+import { createFeedRouteHandler } from '@ampless/runtime/routes'
+
+export const dynamic = 'force-dynamic'
+export const GET = createFeedRouteHandler(ampless)

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

@@ -0,0 +1,6 @@
+import { ampless } from '@/lib/ampless'
+import { createOgRouteHandler } from '@ampless/runtime/routes'
+
+export const runtime = 'nodejs'
+export const dynamic = 'force-dynamic'
+export const GET = createOgRouteHandler(ampless)

package/dist/templates/_shared/app/site/[siteId]/page.tsx

@@ -0,0 +1,10 @@
+import { ampless } from '@/lib/ampless'
+import {
+  createThemeHomeDispatcher,
+  createThemeHomeMetadata,
+} from '@ampless/runtime/dispatchers'
+
+export const dynamic = 'force-dynamic'
+
+export const generateMetadata = createThemeHomeMetadata(ampless)
+export default createThemeHomeDispatcher(ampless)

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

@@ -0,0 +1,5 @@
+import { ampless } from '@/lib/ampless'
+import { createRawRouteHandler } from '@ampless/runtime/routes'
+
+export const dynamic = 'force-dynamic'
+export const GET = createRawRouteHandler(ampless)

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

@@ -0,0 +1,5 @@
+import { ampless } from '@/lib/ampless'
+import { createSitemapRouteHandler } from '@ampless/runtime/routes'
+
+export const dynamic = 'force-dynamic'
+export const GET = createSitemapRouteHandler(ampless)

package/dist/templates/_shared/app/site/[siteId]/tag/[tag]/page.tsx

@@ -0,0 +1,10 @@
+import { ampless } from '@/lib/ampless'
+import {
+  createThemeTagDispatcher,
+  createThemeTagMetadata,
+} from '@ampless/runtime/dispatchers'
+
+export const dynamic = 'force-dynamic'
+
+export const generateMetadata = createThemeTagMetadata(ampless)
+export default createThemeTagDispatcher(ampless)

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

@@ -0,0 +1,110 @@
+import { defineConfig } from 'ampless'
+import seoPlugin from '@ampless/plugin-seo'
+import rssPlugin from '@ampless/plugin-rss'
+// import webhookPlugin from '@ampless/plugin-webhook'
+// import ogImagePlugin, { loadFontFromUrl } from '@ampless/plugin-og-image'
+
+export default defineConfig({
+  site: {
+    name: '{{siteName}}',
+    url: 'http://localhost:3000',
+  },
+  // Admin UI language. Built-in dictionaries: 'ja', 'en'. Add more by
+  // dropping `locales/<code>.json` and registering it in `lib/i18n.ts`.
+  locale: 'ja',
+  media: {
+    delivery: 'nextjs',
+    // 'inline'   — images flow inline at imageMaxWidth (default)
+    // 'lightbox' — click an image to enlarge in a fullscreen overlay
+    imageDisplay: 'inline',
+    imageMaxWidth: '100%',
+    // Defaults for the upload-time image processing UI.
+    // Per-upload values override these in the dialog.
+    processing: {
+      maxDimension: 2400,
+      format: 'webp',
+      quality: 0.85,
+      losslessForPng: true,
+    },
+  },
+  // Multi-site config. Leave undefined for single-site operation; the
+  // runtime then serves every request as siteId='default'. To run
+  // multiple sites in one Amplify environment, declare two or more
+  // entries here:
+  //
+  //   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',
+  //     },
+  //   },
+  //
+  // In multi-site mode the middleware forces `Cache-Control: private,
+  // no-store` on public responses (Amplify Hosting's CloudFront cache
+  // key cannot disambiguate by Host). Single-site mode leaves caching
+  // to the default page directives.
+
+  // 'iso'    — YYYY-MM-DD (default; SSR-safe, locale-neutral)
+  // 'long'   — "April 27, 2026" (en-US)
+  // 'locale' — browser/server locale
+  dateFormat: 'iso',
+  // IANA timezone used for date rendering. Pin this so SSR and CSR
+  // always produce the same string. Examples: 'Asia/Tokyo', 'America/New_York'.
+  timezone: 'UTC',
+  // Active plugins. Order doesn't matter; the runtime aggregates metadata
+  // and runs hooks for events each plugin subscribes to.
+  //
+  // Plugin authors:
+  //  - Plugin factories must return a plain `AmplessPlugin` object. Do NOT
+  //    perform side effects at module top level (network calls, FS writes,
+  //    global state) — both trusted and untrusted Lambdas import this file,
+  //    so module-level work runs in every trust context regardless of which
+  //    Lambda actually invokes the plugin's hooks.
+  //  - Hooks must be idempotent. SQS guarantees at-least-once delivery and
+  //    the dispatcher fans out to both queues; a single source MODIFY can
+  //    trigger your hook more than once.
+  //  - Use `ctx.writePublicAsset(key, ...)` for any S3 write — the runtime
+  //    automatically namespaces under `public/plugins/{your-plugin-name}/`.
+  plugins: [
+    seoPlugin({
+      // defaultOgImage: '/og.png',
+      // twitterSite: '@example',
+    }),
+    rssPlugin({
+      limit: 20,
+      // language: 'ja',
+    }),
+    // webhookPlugin({
+    //   endpoints: [
+    //     {
+    //       url: 'https://example.com/webhook',
+    //       secret: process.env.WEBHOOK_SECRET,
+    //       events: ['content.published', 'content.unpublished', 'content.deleted'],
+    //     },
+    //   ],
+    // }),
+    //
+    // 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.
+    //
+    // ogImagePlugin({
+    //   fonts: [
+    //     {
+    //       name: 'Inter',
+    //       data: loadFontFromUrl('https://example.com/fonts/Inter-Regular.ttf'),
+    //       weight: 400,
+    //     },
+    //   ],
+    //   // 'content' picks the first image in the post body. Use 'theme'
+    //   // + themeImageUrl for a fixed banner, or 'none' for text-only.
+    //   image: 'content',
+    // }),
+  ],
+})

package/dist/templates/_shared/components/i18n-provider.tsx

@@ -0,0 +1,7 @@
+// Back-compat shim. I18n provider + hooks moved to `@ampless/admin`
+// (L2 extraction). The component tree mounts the provider inside the
+// admin layout factory; the root layout in `app/layout.tsx` still
+// wraps the public site in this same provider to keep client-side
+// `useT()` calls working from theme-side components too.
+
+export { I18nProvider, useT, useLocale } from '@ampless/admin/components'

package/dist/templates/_shared/components/lightbox-content.tsx

@@ -0,0 +1,69 @@
+'use client'
+
+import { useEffect, useState } from 'react'
+
+interface LightboxBinderProps {
+  scopeSelector: string
+  /** Site default. Per-image data-display always wins over this. */
+  defaultLightbox?: boolean
+}
+
+// Wires click-to-enlarge for images inside any element. An image opts in
+// when either its `data-display="lightbox"` attribute is set or the site
+// default enables it (and the image hasn't opted out via data-display="inline").
+export function LightboxBinder({ scopeSelector, defaultLightbox = false }: LightboxBinderProps) {
+  const [src, setSrc] = useState<string | null>(null)
+  const [alt, setAlt] = useState<string>('')
+
+  useEffect(() => {
+    const root = document.querySelector(scopeSelector)
+    if (!root) return
+    const imgs = root.querySelectorAll<HTMLImageElement>('img')
+    const cleanup: Array<() => void> = []
+    imgs.forEach((img) => {
+      const display = img.dataset.display
+      const enabled = display === 'lightbox' || (display !== 'inline' && defaultLightbox)
+      if (!enabled) return
+      img.style.cursor = 'zoom-in'
+      const onClick = () => {
+        setSrc(img.src)
+        setAlt(img.alt)
+      }
+      img.addEventListener('click', onClick)
+      cleanup.push(() => img.removeEventListener('click', onClick))
+    })
+    return () => {
+      cleanup.forEach((fn) => fn())
+    }
+  }, [scopeSelector, defaultLightbox])
+
+  useEffect(() => {
+    function onKey(e: KeyboardEvent) {
+      if (e.key === 'Escape') setSrc(null)
+    }
+    if (src) {
+      document.addEventListener('keydown', onKey)
+      return () => document.removeEventListener('keydown', onKey)
+    }
+  }, [src])
+
+  if (!src) return null
+
+  return (
+    <div
+      className="fixed inset-0 z-50 flex items-center justify-center bg-black/85 p-4"
+      onClick={() => setSrc(null)}
+      role="dialog"
+      aria-modal="true"
+    >
+      {/* eslint-disable-next-line @next/next/no-img-element */}
+      <img
+        src={src}
+        alt={alt}
+        className="max-h-full max-w-full object-contain"
+        style={{ cursor: 'zoom-out' }}
+        onClick={(e) => e.stopPropagation()}
+      />
+    </div>
+  )
+}