@justanarthur/payload-www 0.3.5 → 1.2.0

package/README.md

@@ -1,382 +1,392 @@
 # @justanarthur/payload-www
 
-Reusable Payload CMS website template. Wires collections, globals,
-blocks, fields, access, hooks, metadata (JSON-LD, hreflang), and
-Next.js page renderers behind a single `createWWWConfig({ locales, blocks })`
-composer. The lib consumes your [next-intl](https://next-intl.dev) routing
-config so locale validation, URL shape, hreflang alternates, and the
-language switcher share a single source of truth with the rest of your app.
+A reusable Payload CMS website template: collections, globals, blocks, fields, access, JSON-LD / hreflang metadata, Next.js page renderers, sitemap, and the default plugin set (SEO + imagehash + translator + MCP).
+
+The lib reads your [next-intl](https://next-intl.dev) routing config so locale validation, URL shape,
+hreflang alternates, and the language switcher share a single source of truth with the rest of the
+app.
+
+The composition root is `createWWWConfig()` — see [Quick start](#quick-start) below.
 
 ## What's inside
 
-- **Composer** — `createWWWConfig({ locales, blocks, defaultPlugins? })` returns `{ withWWWConfig }`. One composer call is enough for the most common cases.
-- **Collections** — `Pages` (title, blocks tab, slug, drafts, revalidation hook), `Posts` (title, excerpt, richText, drafts, revalidation hook), `StaticPages` (system pages — 404, 500, search-empty, … — addressed by a `kind` discriminator, not a slug)
-- **Globals** — `Header` and `Footer` (both `nav` blocks with `navColumn` / `navItem`). Extend the nav link schema (e.g. a `description` or a `navHover` mega-menu group) via `createHeaderGlobal({ navColumnLinkFields, navItemLinkFields })` / `createFooterGlobal({ … })`, or `link({ extraFields })` directly.
-- **Default render components** — `PagesPage`, `HeaderPage`, `FooterPage` Server Components. Override any of them by setting a different `custom.path` on the collection / global.
-- **LivePreviewListener** — built in. The lib's `createCollectionPageExports` default page renders it (via `React.lazy` so the server dist stays free of `'use client'` imports) whenever Next.js draft mode is on. Hosts get live preview automatically — no opt-in required. The component itself is also exported from `/render-components` for hosts that want to mount it elsewhere.
-- **Hooks** — `createRevalidateCollectionHook(opts)` (canonical factory for **all** collections: Pages, Posts, host-defined; per-locale `revalidatePath` fan-out + `revalidateTag('collection_<slug>_<id>', 'max')` + sitemap tag, with a `pathMode: 'tag-only'` mode for collections without a URL like `staticPages`), `createRevalidatePageHooks()` (deprecated alias for Pages preset), `createRevalidateGlobalHook(slug)` (per-locale tag for globals)
-- **Access** — `anyone`, `authenticated`, `authenticatedOrPublished`
-- **Fields** — `link`, `linkGroup` (with `disableLabel` / `appearances` / `localized` / `relationTo` / `overrides` options)
-- **Metadata** — `buildArticleLd`, `buildBreadcrumbsLd`, `buildOrganizationLd`, `buildHreflangAlternates`, slug transforms, `queryDocBySlug` / `queryAllDocs` / `queryAllLocaleSlugs`
-- **Pages** — `createCollectionPageExports` (Next.js App Router render factory), `addCollectionsToSitemap`. Supports a `showcase` sidebar and a `homeExtras` callback for the home route.
-- **Components** — `LivePreviewListener`, `RenderBlocks`, `PageShowcase` (sidebar layout for demos / previews), `LocaleSwitcher` (server-renderable nav built from the page's hreflang alternates)
-- **Route handlers** — `createPreviewHandler` (from the `/render-utils` subpath). The Next.js sitemap convention ships as `createSitemapFile` (same subpath) — it's a `MetadataRoute.Sitemap` factory for `app/(frontend)/sitemap.ts`, not a route handler, and it's `localePrefix`-aware.
-- **Utils** — `getFromImportMap`, `generateImportName`, `renderCollectionModule`
-- **Seed / Test** — `createBaseSeed` (publishes by default — pass `status: 'draft'` to keep a doc as a draft), `createTestPayload`
+| piece | exported from | purpose |
+|---|---|---|
+| Composer | [`/config`](#quick-start) | `createWWWConfig()` — returns `{ withWWWConfig }`. One call wires Pages + Posts + Header + Footer + the default plugin set. |
+| Pages + Posts collections | `createPagesCollection`, `createPostsCollection` (internal — composed by the composer) | Pages (title, blocks tab, slug, drafts, revalidation); Posts (title, excerpt, richText, drafts, revalidation). |
+| Header + Footer globals | `createHeaderGlobal`, `createFooterGlobal` (internal) | Both nav blocks with `navColumn` / `navItem`. Extend via `link({ extraFields })`. |
+| Static-page collection | `createWWWCollectionGlobal` ([`/collections`](#collections)) | Generic factory for system pages (404, 500, search-empty) — keyed by a discriminator, no slug. |
+| Default plugins | composed by `createWWWConfig()` | `seoPlugin`, `imageHashPlugin`, `translator`, `mcpPlugin`. Tune via `defaultPluginsConfigs`. |
+| Fields | [`/fields`](#fields) | `link`, `linkGroup` (with `disableLabel` / `appearances` / `localized` / `relationTo` / `extraFields`), `slugField`, `appearanceOptions`. |
+| Access | [`/access`](#access) | `anyone`, `authenticated`, `authenticatedOrPublished`. |
+| Revalidation hooks | [`/collections`](#collections) (`createRevalidateCollectionGlobalHook`, `createCollectionCacheKey`, `populatePublishedAt`) | Tag-based cache invalidation + published-at population. |
+| Metadata | [`/metadata`](#metadata) | `buildArticleLd`, `buildBreadcrumbsLd`, `buildOrganizationLd`, `buildWebSiteLd`, `buildProductLd`, `buildRootJsonLd`; slug transforms; `queryDocBySlug`, `queryAllDocs`, `queryAllLocaleSlugs`. |
+| Next.js page renderers | [`/render-pages`](#render-pages) | `createCollectionPageExports`, `createRootLayoutExports`; default render components `PagesPage`, `PostsPage`, `HeaderPage`, `FooterPage`, `RootJsonLd`. |
+| Sitemap | [`/sitemap`](#sitemap) | `createSitemapFromCollections` (Next.js file-convention helper). |
+| Plugin re-exports | [`/imagehash`](#plugin-re-exports), [`/translator`](#plugin-re-exports) | Drop-in for hosts that don't want to import the sibling packages directly. |
 
 ## Quick start
 
-### 1. Wire the composer
-
 ```ts
 // payload.config.ts
 import { buildConfig } from 'payload'
-import { createWWWConfig } from '@justanarthur/payload-www/with-www-config'
-import { MyCtaBlock, MyHeroBlock, MyRichTextBlock } from './blocks'
+import { createWWWConfig } from '@justanarthur/payload-www/config'
+import { blocks } from '@/components/blocks'
+import { plugins } from '@/plugins'
+
+const { withWWWConfig } = createWWWConfig()
+
+export default buildConfig(withWWWConfig({
+  blocks,                                  // Page block set
+  plugins,                                 // host plugins appended after the lib's defaults
+  collections: (defaults) => [
+    ...defaults,
+    Media,
+    Users
+  ],
+  globals: (defaults) => [
+    ...defaults.map(g => g.slug === 'header'
+      ? { ...g, custom: { [payloadWwwName]: { path: '@/components/Header/Component#Header' } }, fields: headerFields }
+      : g.slug === 'footer'
+        ? { ...g, custom: { [payloadWwwName]: { path: '@/components/Footer/Component#Footer' } }, fields: footerFields }
+        : g),
+    createStaticGlobal(),
+    createMessagesGlobal()
+  ],
+  defaultPluginsConfigs: {                 // tune the lib's default plugin set
+    seo:        (d) => ({ ...d, collections: ['pages', 'posts'], openaiApiKey: process.env.OPENAI_API_KEY }),
+    imageHash:  (d) => ({ ...d, algorithm: 'lqip-modern' }),
+    translator: (d) => ({ ...d, autoTranslate: true, collections: ['pages', 'posts'], globals: ['header', 'footer', 'messages'] })
+  },
+  localization: { /* ... */ },
+  db: postgresAdapter({ /* ... */ }),
+  // ...rest of Payload config
+}))
+```
 
-const { withWWWConfig } = createWWWConfig({
-  locales: ['en', 'sk', 'de'],
-  blocks: [MyCtaBlock, MyHeroBlock, MyRichTextBlock]
-})
+`createWWWConfig()` takes **no arguments**. You tune everything via the `WWWInputConfig` passed to
+`withWWWConfig`. The composer reads its own package name from `package.json` and uses it as the
+`custom.<packageName>` key — that's how the block / collection / global `custom.path` entries get
+threaded into Payload's import map.
 
-export default buildConfig(
-  withWWWConfig({
-    collections: [],   // optional extra collections
-    globals: [],      // optional extra globals
-    // ...rest of your config
-  })
-)
-```
+The `defaultPluginsConfigs` map lets you keep the defaults (seoPlugin, imageHashPlugin, translator,
+mcpPlugin) and tweak their constructor args without re-importing them. Pass `(defaults) => …` to
+merge or `…` to replace.
 
-`withWWWConfig` injects `Pages`, `Header`, and `Footer` plus the lib's
-default plugin set (seoPlugin, imageHashPlugin, translator). Use the
-`defaultPlugins` callback to drop or extend the list:
+## Page exports (Next.js App Router)
 
 ```ts
-createWWWConfig({
-  locales: ['en', 'sk', 'de'],
-  blocks: [MyCtaBlock],
-  defaultPlugins: (defaults) => defaults.filter((p) => p !== translator)
-})
-```
-
-### 2. Define your next-intl routing
+// app/(frontend)/[locale]/layout.tsx
+import { createRootLayoutExports } from '@justanarthur/payload-www/render-pages'
+import { importMap } from '@/app/(payload)/admin/importMap'
+import { routing } from '@/i18n/routing'
+import config from '@payload-config'
+import { getServerSideURL } from '@/lib/utils/getURL'
 
-The lib reads the same routing config next-intl uses, so URL shape,
-locale validation, hreflang alternates, and the language switcher share
-a single source of truth:
+const { default: RootLayout, generateStaticParams } = createRootLayoutExports(
+  { config, importMap, routing },
+  { getServerSideURL }
+)
 
-```ts
-// src/i18n/routing.ts
-import { defineRouting } from 'next-intl/routing'
-
-export const routing = defineRouting({
-  locales: ['en', 'uk'],
-  defaultLocale: 'en',
-  // 'as-needed' means `/about` for the default locale and
-  // `/uk/about` for the others — the lib mirrors this in
-  // hreflang alternates and the language switcher.
-  localePrefix: 'as-needed',
-  labels: { en: 'English', uk: 'Українська' }
-})
+export default RootLayout
+export { generateStaticParams }
 ```
 
-### 3. Page exports
-
 ```ts
-// app/(frontend)/[locale]/page.tsx — home
-// app/(frontend)/[locale]/[...slug]/page.tsx — catch-all
+// app/(frontend)/[locale]/[[...slug]]/page.tsx — Pages home + catch-all
 import { createCollectionPageExports } from '@justanarthur/payload-www/render-pages'
-import configPromise from '@payload-config'
-import { importMap } from '@/app/(payload)/admin/importMap.js'
+import config from '@payload-config'
+import { importMap } from '@/app/(payload)/admin/importMap'
 import { routing } from '@/i18n/routing'
-
-import { getServerSideURL } from '@/utilities/getURL'
-
-const generateMeta = async ({ doc }) => ({ title: doc?.title })
-
-const { default: Page, generateMetadata, generateStaticParams } =
-  createCollectionPageExports(
-    { config: configPromise, importMap, routing },
-    { getServerSideURL, generateMeta }
-  )
+import { getServerSideURL } from '@/lib/utils/getURL'
+
+const {
+  default: Page,
+  generateMetadata,
+  generateStaticParams,
+  generateSitemap
+} = createCollectionPageExports(
+  { config, importMap, routing, slugShape: 'catch-all' },
+  { getServerSideURL }
+)
 
 export default Page
-export { generateMetadata, generateStaticParams }
+export { generateMetadata, generateStaticParams, generateSitemap }
 ```
 
-The lib auto-mounts its `LivePreviewListener` (loaded via `React.lazy`
-so the server dist stays free of `'use client'` imports) whenever
-Next.js draft mode is on. No opt-in required.
-
-#### Showcase sidebar + home extras
-
-The home route can render inside a `<PageShowcase>` two-column layout
-(sidebar with metadata, JSON-LD, and a language switcher) and append a
-`homeExtras` block (recent pages, recent posts, etc.):
+`slugShape` is `'single'` (default) or `'catch-all'`. Use `'catch-all'` if your route segment is
+`[[...slug]]` (Pages-style), `'single'` for `[slug]` (Posts-style — file convention).
 
 ```ts
-const { default: Page, generateMetadata, generateStaticParams } =
-  createCollectionPageExports(
-    { config: configPromise, importMap, routing },
-    {
-      getServerSideURL,
-      generateMeta,
-      showcase: { enabled: true },                 // wrap in <PageShowcase>
-      homeExtras: async ({ locale }) => {
-        const { pages, posts } = await fetchRecent(locale)
-        return <RecentLists pages={pages} posts={posts} />
-      }
-    }
-  )
+// app/(frontend)/[locale]/posts/[slug]/page.tsx
+const { default: PostPage, generateMetadata, generateStaticParams } = createCollectionPageExports(
+  { config, importMap, routing, slug: 'posts', slugShape: 'single' },
+  { getServerSideURL }
+)
 ```
 
-`<PageShowcase>` and `<LocaleSwitcher>` are also exported individually
-(from `/render-components` and `/render-utils` respectively) for hosts
-that want to drop them in their own layouts.
+### `createCollectionPageExports(args, deps)` — args
+
+| arg | type | default | notes |
+|---|---|---|---|
+| `config` | `Promise<SanitizedConfig>` | required | the host's `payload.config.ts` |
+| `importMap` | `ImportMap` | required | the host's `app/(payload)/admin/importMap` |
+| `routing` | `RoutingConfig` | required | `{ locales, defaultLocale, localePrefix, labels? }` from `next-intl/routing`'s `defineRouting` |
+| `slug` | `string` | `'pages'` | collection slug to query |
+| `slugShape` | `'single' \| 'catch-all'` | `'single'` | drives `generateStaticParams` + slug segmentation |
 
-### 4. Route handlers — preview + sitemap
+### `createCollectionPageExports(args, deps)` — deps
+
+| dep | type | notes |
+|---|---|---|
+| `getServerSideURL` | `() => string` | host's absolute-URL helper |
+| `pagePathPrefix` | `string` | optional URL prefix for `generateSitemap` only — not used for rendering |
+
+### What you get back
 
 ```ts
-// src/proxy.ts (replaces the deprecated src/middleware.ts)
-import createMiddleware from 'next-intl/middleware'
-import { routing } from '@/i18n/routing'
-export default createMiddleware(routing)
-export const config = {
-  matcher: ['/', '/((?!api|_next|_vercel|admin|next|.*\\..*).*)']
+{
+  default: Page,           // the page component
+  generateMetadata,        // Next.js MetadataRoute hook
+  generateStaticParams,    // Next.js static-params hook
+  generateSitemap          // MetadataRoute.Sitemap producer for /sitemap.ts
 }
 ```
 
-```ts
-// app/(payload)/next/preview/route.ts
-import { createPreviewHandler } from '@justanarthur/payload-www/render-utils'
-export const GET = createPreviewHandler()
-```
+### `createRootLayoutExports(args, deps)`
+
+| arg | type | notes |
+|---|---|---|
+| `config` | `Promise<SanitizedConfig>` | required |
+| `importMap` | `ImportMap` | required |
+| `routing` | `RoutingConfig` | required |
+
+| dep | type | notes |
+|---|---|---|
+| `getServerSideURL` | `() => string` | if provided, the SEO plugin's `RootJsonLd` (`Organization` / `WebSite` JSON-LD) is auto-injected as the first child of `<html>` |
+| `providers` | `(args) => ReactNode` | wraps `{children}` between the rendered Header and Footer |
+| `htmlAttrs` | `(locale) => HTMLAttributes<HTMLHtmlElement>` | extra `<html>` attributes per locale (defaults: `lang={locale}`, `suppressHydrationWarning`) |
+
+The layout reads `header` + `footer` globals in parallel and wraps the children in
+`<NextIntlClientProvider>`. Locale is pulled from the `[locale]` route segment and validated against
+`routing.locales` — unknown locales trigger `notFound()`.
+
+## Sitemap
 
 ```ts
 // app/(frontend)/sitemap.ts
-import { createSitemapFile } from '@justanarthur/payload-www/render-utils'
-import configPromise from '@payload-config'
-import { getServerSideURL } from '@/utilities/getURL'
-
-// One file, all collections, all locales — Next.js serves it at
-// /sitemap.xml. The Pages collection's `afterChange` hook invalidates
-// the `pages-sitemap` tag the factory reads from, so edits refresh
-// the sitemap automatically.
-export default createSitemapFile({
-  collections: ['pages', 'posts'],
-  config: configPromise,
+import { createSitemapFromCollections } from '@justanarthur/payload-www/sitemap'
+import config from '@payload-config'
+import { getServerSideURL } from '@/lib/utils/getURL'
+
+export default createSitemapFromCollections({
+  getServerSideURL,
+  pagePathPrefix: ''                    // empty for root-mounted (Pages)
+  // pagePathPrefix: '/posts'           // use this for the Posts catch-all
+}, {
   getServerSideURL,
-  // 'as-needed' makes the default locale render without a prefix
-  // (`/about`), other locales prefixed (`/uk/about`). Matches the
-  // host's next-intl `localePrefix` so sitemap URLs match the
-  // actual route shape.
-  localePrefix: 'as-needed',
-  // Collections mounted under a sub-route (here: Posts at
-  // `/posts/[...slug]`) need their sitemap URLs prefixed so they
-  // match the real route. Pages live at the root, so no prefix.
-  urlPrefixes: { posts: '/posts' }
+  pagePathPrefix: '/posts'
 })
 ```
 
-The Pages collection's `afterChange` hook revalidates the
-`pages-sitemap` tag the sitemap factory reads from.
+`createSitemapFromCollections(...args)` takes one or more deps-shaped objects (the same shape
+`createCollectionPageExports`'s deps accept) and returns a Next.js `MetadataRoute.Sitemap`-compatible
+function. Mount one per collection under a sub-route, or a single call for the root.
 
-### 5. System pages (404, 500, search-empty, …)
+The lib's Pages `afterChange` hook fires `revalidateTag(collection_pages_<slug>_<locale>, 'max')`,
+which is the key `createCollectionPageExports` / `createSitemapFromCollections` reads from — so
+edits refresh the sitemap without manual rebuilds.
 
-The lib ships a `StaticPages` collection for pages that don't map to a
-slug-based URL. One row per `kind` discriminator (`'not-found'`,
-`'server-error'`, `'search-empty'`, `'offline'`). The host's route
-file fetches the row and renders it via `createStaticPageExports` —
-the same shape as `createCollectionPageExports`, minus the
-metadata / sitemap / static-params plumbing (system pages have no
-URL):
+## Static pages (404 / 500 / system)
+
+There's no dedicated `createStaticPageExports` (yet). System pages render via a normal
+`createCollectionPageExports({ slug: 'static-pages', slugShape: 'single' })` mount, addressed by a
+discriminator instead of a slug:
 
 ```ts
 // app/(frontend)/[locale]/not-found.tsx
-import configPromise from '@payload-config'
-import { createStaticPageExports } from '@justanarthur/payload-www/render-pages'
-import { importMap } from '@/app/(payload)/admin/importMap.js'
-
-const { default: NotFound } = createStaticPageExports({
-  config: configPromise,
-  importMap,
-})
+const { default: NotFound } = createCollectionPageExports(
+  { config, importMap, routing, slug: 'static-pages', slugShape: 'single' },
+  { getServerSideURL }
+)
 
 export default NotFound
 ```
 
-`createStaticPageExports` reads the active locale via
-`getLocale()` from `next-intl/server` (Next.js passes no props to
-not-found components, so the URL-segment locale comes from the
-request config — middleware sets it, the host's `i18n/request.ts`
-falls back to `defaultLocale` for invalid values). Adding a
-`server-error.tsx` is the same shape with `kind: 'server-error'`.
+The `static-pages` collection is built via `createWWWCollectionGlobal({...}, { slug: 'static-pages', renderPath: '@/components/StaticPage/Component#StaticPage', isDraft: false })`. Editors pick a `kind` (`'not-found'`, `'server-error'`, `'search-empty'`, `'offline'`), populate the `blocks` tab with the same block set you passed to `createWWWConfig`, and the host's not-found / server-error route renders the row. `populatePublishedAt` and the revalidation hooks are wired automatically.
+
+## Collections
+
+```ts
+import {
+  createWWWCollectionGlobal,         // generic factory (used internally for static-pages)
+  createRevalidateCollectionGlobalHook, // the afterChange/afterDelete pair
+  createCollectionCacheKey,          // produces the tag string
+  queryDoc                          // server-side helper used by renderers
+} from '@justanarthur/payload-www/collections'
+```
+
+`createWWWCollectionGlobal(fields, { slug, renderPath, isGlobalConfig?, isDraft? })`:
+
+| arg | type | notes |
+|---|---|---|
+| `fields` | `Field[]` | the collection's field set (the factory adds `slug`, `publishedAt`, access, hooks) |
+| `slug` | `string` | collection slug |
+| `renderPath` | `string` | import-map path to the render component (`'@/components/Foo/Component#Foo'`) |
+| `isGlobalConfig` | `boolean` | `true` for globals, `false` (default) for collections |
+| `isDraft` | `boolean` | `true` (default) enables Payload's drafts + autosave; `false` for system pages |
 
-Editors create the row in admin (under the `System` group), pick a
-`kind`, and populate the `blocks` tab using the same block set you
-passed to `createWWWConfig({ blocks })`. The `title` field is
-admin-only — not rendered. `kind` is `unique`, so the database
-enforces one row per system page. Drafts + autosave mirror `pages`.
-The translator plugin includes `'static-pages'` in its default
-`collections` list, so SK content fills automatically when you expand
-`localization.locales`.
+The factory wires `custom[packageName] = { path: renderPath }`, access (`create`/`update`/`delete`
+require auth, `read` is `anyone` or `authenticatedOrPublished` depending on `isDraft`), the
+`afterChange`/`afterDelete` revalidation hook, and `populatePublishedAt` (`beforeChange`).
 
-Revalidation uses the `pathMode: 'tag-only'` branch of
-`createRevalidateCollectionHook` — no URL fan-out (system pages have
-no slug), but the per-id tag (`collection_static-pages_<id>`) and the
-collection-wide tag (`static-pages` via the `sitemapTag` override)
-fire on every change.
+### Revalidation
 
-## Public API
+`createRevalidateCollectionGlobalHook()` returns `{ afterChange, afterDelete }` — the same function
+used for both. On every save / delete of a published doc it fires:
 
-The root import gives you the full surface:
+```
+revalidateTag(`<slug><slug>_<locale>`, 'max')   // collections
+revalidateTag(`<globalSlug>_<locale>`, 'max')  // globals
+```
+
+`createCollectionCacheKey({ collectionSlug, slug, locale })` produces the same key string — use it
+in your own `unstable_cache` / `fetch` cache keys if you want them invalidated by the lib's hooks.
+
+> The `// @ts-expect-error` and `// todo sitemap caching and revalidation` markers in
+> `createRevalidateCollectionGlobalHook.ts` are intentional, not bugs — the hook covers tag-based
+> invalidation; URL revalidation and the unified sitemap tag are still TODO.
+
+## Fields
+
+```ts
+import { link, linkGroup, appearanceOptions, slugField } from '@justanarthur/payload-www/fields'
+
+// link({ extraFields: [...] })        — append host fields (description, navHover, …)
+// linkGroup({ appearances: ['default', 'outline'] })
+// slugField({ localized: false, nested: true })
+// appearanceOptions                    — for selects that should match link `appearances`
+```
+
+`link({ extraFields })` is the extension point for host-specific nav-link shapes. The lib's
+`createHeaderGlobal` / `createFooterGlobal` accept `navColumnLinkFields` / `navItemLinkFields` that
+are forwarded into their `navColumn` / `navItem` blocks.
+
+## Access
+
+```ts
+import { anyone, authenticated, authenticatedOrPublished } from '@justanarthur/payload-www/access'
+```
+
+- `anyone` — always true.
+- `authenticated` — true when the request has a user.
+- `authenticatedOrPublished` — true when authenticated **or** the doc is `_status: 'published'`.
+
+## Metadata
 
 ```ts
 import {
-  createWWWConfig,           // composer (default export)
-  createPagesCollection,     // collection factories
-  createPostsCollection,
-  createStaticPagesCollection,
-  createHeaderGlobal,
-  createFooterGlobal,
-  generatePreviewPath,       // admin.preview URL builder
-  HOME_PAGE_SLUG, PAGES_SLUG, POSTS_SLUG, STATIC_PAGES_SLUG,
-  link, linkGroup,           // fields
-  appearanceOptions,
-  anyone, authenticated,     // access
-  authenticatedOrPublished,
-  createRevalidatePageHooks, // hooks
-  createRevalidateCollectionHook, // hooks (canonical; createRevalidatePageHooks is a deprecated Pages preset)
-  createRevalidateGlobalHook,
-  buildArticleLd,            // metadata
-  buildBreadcrumbsLd,
+  buildArticleLd,           // Article JSON-LD
+  buildBreadcrumbsLd,       // BreadcrumbList JSON-LD
   buildOrganizationLd,
-  buildHreflangAlternates,
-  queryDocBySlug, queryAllDocs, queryAllLocaleSlugs,
-  segmentsToStoredSlug, segmentsToUrlPath, storedSlugToSegments,
-  getUrlPath, buildCanonicalUrl,
-  createCollectionPageExports,  // page factory
-  addCollectionsToSitemap,
-  LivePreviewListener, RenderBlocks,  // components
-  PageShowcase, LocaleSwitcher,       // demo / preview components
-  getFromImportMap, generateImportName, renderCollectionModule,  // utils
-  createBaseSeed, createTestPayload,  // dev
-  // constants
-  PAGES_RENDER_PATH, HEADER_RENDER_PATH, FOOTER_RENDER_PATH, PAGES_SITEMAP_TAG
-} from '@justanarthur/payload-www'
+  buildWebSiteLd,
+  buildProductLd,
+  buildRootJsonLd,          // combined Organization + WebSite + Product (used by RootJsonLd)
+  queryDocBySlug,
+  queryAllDocs,             // for generateStaticParams
+  queryAllLocaleSlugs,      // for hreflang alternates
+  paramsSlugToSlug,         // turn [locale]/[[...slug]] params → stored slug
+  slugToParamsSlug          // turn stored slug → params for generateStaticParams
+} from '@justanarthur/payload-www/metadata'
+```
+
+## Blocks
+
+```tsx
+import { RenderBlocks } from '@justanarthur/payload-www/blocks'
+
+export function PageBody({ blocks }) {
+  return <RenderBlocks blocks={blocks} />
+}
+```
+
+`RenderBlocks` reads each block's `custom[packageName].path` from Payload and dynamically imports
+the matching component from the host's `importMap`.
+
+## Plugin re-exports
+
+```ts
+import { imageHashPlugin } from '@justanarthur/payload-www/imagehash'
+import { translator }      from '@justanarthur/payload-www/translator'
+import { seoPlugin }       from '@justanarthur/payload-plugin-seo'          // no re-export here, import directly
+import { mcpPlugin }       from '@payloadcms/plugin-mcp'                    // no re-export here, import directly
 ```
 
-Subpath imports:
-
-| Subpath                          | What's there                                                |
-|----------------------------------|-------------------------------------------------------------|
-| `@justanarthur/payload-www`      | root: `LivePreviewListener` only (client-safe)              |
-| `@justanarthur/payload-www/server` | everything else                                          |
-| `@justanarthur/payload-www/with-www-config` | `createWWWConfig` (default export)                |
-| `@justanarthur/payload-www/collections`    | `createPagesCollection`, `createHeaderGlobal`, `createFooterGlobal` |
-| `@justanarthur/payload-www/globals`        | `createHeaderGlobal`, `createFooterGlobal`        |
-| `@justanarthur/payload-www/hooks`          | revalidation hooks                                |
-| `@justanarthur/payload-www/pages`          | `createCollectionPageExports`, `addCollectionsToSitemap` |
-| `@justanarthur/payload-www/render-pages`   | same as `/pages` + `PagesPage` / `HeaderPage` / `FooterPage` / `PageShowcase` |
-| `@justanarthur/payload-www/render-utils`   | `createPreviewHandler`, `createSitemapFile`, `LivePreviewListener`, `LocaleSwitcher` |
-| `@justanarthur/payload-www/render-components` | `LivePreviewListener`                            |
-| `@justanarthur/payload-www/render-metadata` | JSON-LD + hreflang + slug utilities               |
-| `@justanarthur/payload-www/metadata`       | same as `/render-metadata`                        |
-| `@justanarthur/payload-www/fields`         | `link`, `linkGroup`, `appearanceOptions`          |
-| `@justanarthur/payload-www/access`         | `anyone`, `authenticated`, `authenticatedOrPublished` |
-| `@justanarthur/payload-www/blocks`         | `RenderBlocks`                                    |
-| `@justanarthur/payload-www/components`     | `LivePreviewListener`                             |
-| `@justanarthur/payload-www/utils`          | `getFromImportMap`, `generateImportName`, `renderCollectionModule` |
-| `@justanarthur/payload-www/seed`           | `createBaseSeed`                                  |
-| `@justanarthur/payload-www/test`           | `createTestPayload`                               |
-| `@justanarthur/payload-www/data-seed`      | same as `/seed`                                   |
-| `@justanarthur/payload-www/data-test`      | same as `/test`                                   |
-| `@justanarthur/payload-www/data-collections` | collection factories                             |
-| `@justanarthur/payload-www/config`         | `createWWWConfig` (default export)                |
-| `@justanarthur/payload-www/imagehash`      | `imageHashPlugin` re-export                       |
-| `@justanarthur/payload-www/translator`     | `translator` re-export                            |
-
-## Configuration reference
-
-`createWWWConfig({ ... })`:
-
-| Option           | Type                              | Required | Description                                                            |
-|------------------|-----------------------------------|----------|------------------------------------------------------------------------|
-| `locales`        | `string[]`                        | yes      | Locale list. First entry is the default locale (translation source).   |
-| `routing`        | `PageRouting`                     | no       | The host's next-intl `defineRouting({...})` result. When passed, `locales`, `defaultLocale`, and `localePrefix` are read from this object. `localePrefix` accepts both the simple string form and next-intl's verbose `{ mode, prefixes? }` shape (normalized internally). |
-| `blocks`         | `Block[]`                         | yes      | Blocks the Pages collection accepts.                                   |
-| `linkRelationTo` | `string[]`                        | no       | Collection slugs the Header / Footer nav links can reference. Default: `['pages']`. |
-| `registerPosts`  | `boolean`                         | no       | Register the lib's Posts collection. Default `true`. |
-| `nested`         | `boolean`                         | no       | Enable nested Pages slugs (`about_us` → `/about/us`). Relaxes the Pages slug validation to accept the `_` divider. Pass the same `nested: true` to `createCollectionPageExports` on the Pages route (and `nested: { pages: true }` to `createSitemapFile`). Default `false`. |
-| StaticPages      | —                                 | yes      | Always registered (every site has 404). Hosts filter it out in `collections:` to opt. |
-| `defaultPlugins` | `(defaults: Plugin[]) => Plugin[]`| no       | Final say on the default `[seoPlugin, imageHashPlugin, translator]` list. |
-
-`createRevalidateCollectionHook({ collectionSlug, urlPathPrefix?, sitemapTag?, localePrefix?, defaultLocale? })`:
-
-| Option           | Type                              | Description                                                            |
-|------------------|-----------------------------------|------------------------------------------------------------------------|
-| `collectionSlug` | `string`                          | Required. The collection's slug. Used in the `collection_<slug>_<id>` tag. |
-| `urlPathPrefix`  | `string`                          | URL path prefix. `''` for root-mounted (Pages), `'/posts'` for Posts. Default `''`. |
-| `sitemapTag`     | `string \| false`                 | Tag fired alongside paths. Default `${collectionSlug}-sitemap`. Pass `false` to opt out. |
-| `localePrefix`   | `'always' \| 'as-needed' \| 'never'` | Mirrors next-intl. Default `'always'`. Set to `'as-needed'` (with `defaultLocale`) when the host uses as-needed routing. |
-| `defaultLocale`  | `string`                          | Default locale for `localePrefix: 'as-needed'`. Falls back to `req.payload.config.localization.defaultLocale`. |
-| `pathMode`       | `'url' \| 'tag-only'`             | Default `'url'` — fans out `revalidatePath` per locale × slug. Set `'tag-only'` for collections without a URL (e.g. `staticPages`); the hook still fires the per-id tag (`collection_<slug>_<id>`) and the collection-wide tag (via `sitemapTag`). |
-
-The canonical hook for all collections — Pages, Posts, and host-defined. Pages internally uses this with `collectionSlug: 'pages'`, `urlPathPrefix: ''`. Fires `revalidatePath` for **every** declared locale (not just the request locale), handles slug renames while published, fires `revalidateTag('collection_<slug>_<id>', 'max')` for hosts that cache by id, and respects `req.context.disableRevalidate` for seed scripts.
-
-`createRevalidatePageHooks()` is a deprecated alias for `createRevalidateCollectionHook({ collectionSlug: 'pages', urlPathPrefix: '' })` — kept for backward compat with hosts that imported this name directly.
-
-`createCollectionPageExports({ config, importMap, slug?, renderPath?, routing }, deps, options?)`:
-
-| Param        | Type            | Description                                                            |
-|--------------|-----------------|------------------------------------------------------------------------|
-| `config`     | `Promise<SanitizedConfig>` | Resolved Payload config from `payload.config.ts`         |
-| `importMap`  | `ImportMap`     | The host's `app/(payload)/admin/importMap.js`                          |
-| `slug`       | `string`        | Default `'pages'`                                                      |
-| `renderPath` | `string`        | Override the lib's `PAGES_RENDER_PATH`                                 |
-| `routing`    | `PageRouting`   | The host's `defineRouting({...})` result — drives URL building, hreflang, and the language switcher |
-| `deps.getServerSideURL`     | `() => string` | Host's absolute URL helper                            |
-| `deps.generateMeta`        | `(args) => Promise<Metadata>` | Host's metadata composer        |
-| `deps.notFoundOnMissing`    | `boolean`     | Default `true` — render 404 for unknown slugs                          |
-| `deps.showcase`            | `ShowcaseOptions \| false` | When `{ enabled: true }`, wraps the body in `<PageShowcase>`     |
-| `deps.homeExtras`          | `(args) => ReactNode \| Promise<ReactNode>` | Content appended to the home route (slug = `''`) |
-| `options.jsonLd`           | `boolean \| JsonLdEntry[]` | Default `{ type: 'website' }` for every page         |
-| `options.changefreq`       | `string`      | Default `'weekly'`                                                     |
-| `options.priority`         | `number`      | Default `0.5`                                                          |
-| `options.websiteName`      | `string`      | Override the auto-generated `WebSite` JSON-LD `name`                   |
-
-`createSitemapFile({ ... })`:
-
-| Option          | Type            | Description                                                            |
-|-----------------|-----------------|------------------------------------------------------------------------|
-| `collections`   | `string[]`      | Collection slugs whose docs appear in the sitemap                       |
-| `config`        | `Promise<any>`  | The Payload config promise                                              |
-| `getServerSideURL` | `() => string` | Host's absolute URL helper                                             |
-| `localePrefix`  | `'always' \| 'as-needed' \| 'never'` | Default `'always'`. Mirrors next-intl's `localePrefix` so the sitemap URLs match the host's route shape. With `'as-needed'`, the default locale renders without a prefix. |
-| `locales`       | `string[]`      | Optional locale filter. Defaults to every `config.localization.locales`. |
-| `urlPrefixes`   | `Record<string, string>` | Per-collection URL path prefix. Default `''`. Pass `{ posts: '/posts' }` for a collection mounted under a sub-route. |
-| `perCollection` | `Record<string, { priority?, changefreq? }>` | Per-collection overrides                            |
-
-## Migration notes
-
-- `src/middleware.ts` is deprecated in favor of `src/proxy.ts` (next-intl ≥4). The lib doesn't ship a middleware — wire `createMiddleware(routing)` in your own `proxy.ts`.
-- `PageRouting` is a new required arg on `createCollectionPageExports`. It's a structural subset of the next-intl `defineRouting` result (locales, defaultLocale, localePrefix, labels), so passing your routing object directly works.
-- `createBaseSeed` now sets `_status: 'published'` on created / updated pages and posts by default. Pass `status: 'draft'` per entry to keep it as a draft.
+Use these if you want to compose the default plugin set manually outside `createWWWConfig`. Full
+plugin docs:
+
+- [`@justanarthur/payload-plugin-seo`](../../plugins/seo/README.md)
+- [`@justanarthur/payload-imagehash-plugin`](../../plugins/imagehash/README.md)
+- [`@justanarthur/payload-plugin-translator`](../../plugins/translate/README.md)
+
+## Public subpath exports
+
+The package's `package.json#exports` map:
+
+| Subpath | What's there |
+|---|---|
+| `@justanarthur/payload-www/config` | `createWWWConfig`, `WWWConfigApi`, `WWWInputConfig` |
+| `@justanarthur/payload-www/render-pages` | `createCollectionPageExports`, `createRootLayoutExports`, `PagesPage`, `PostsPage`, `HeaderPage`, `FooterPage`, `RootJsonLd` + types |
+| `@justanarthur/payload-www/pages` | subset of `/render-pages` (no `createRootLayoutExports`, no `PostsPage`, no `RootJsonLd`) |
+| `@justanarthur/payload-www/sitemap` | `createSitemapFromCollections` |
+| `@justanarthur/payload-www/blocks` | `RenderBlocks`, `RenderBlocksProps` |
+| `@justanarthur/payload-www/collections` | `createWWWCollectionGlobal`, `createRevalidateCollectionGlobalHook`, `createCollectionCacheKey`, `queryDoc` |
+| `@justanarthur/payload-www/fields` | `link`, `linkGroup`, `appearanceOptions`, `slugField`, `LinkAppearances`, `LinkOptions` |
+| `@justanarthur/payload-www/access` | `anyone`, `authenticated`, `authenticatedOrPublished` |
+| `@justanarthur/payload-www/metadata` | `buildArticleLd`, `buildBreadcrumbsLd`, `buildOrganizationLd`, `buildWebSiteLd`, `buildProductLd`, `buildRootJsonLd`, `queryDocBySlug`, `queryAllDocs`, `queryAllLocaleSlugs`, `paramsSlugToSlug`, `slugToParamsSlug` + types |
+| `@justanarthur/payload-www/utils` | `generateImportName`, `getFromImportMap` |
+| `@justanarthur/payload-www/imagehash` | `imageHashPlugin`, `BlurhashPluginOptions` (re-export of `@justanarthur/payload-imagehash-plugin`) |
+| `@justanarthur/payload-www/translator` | `translator` (re-export of `@justanarthur/payload-plugin-translator`) |
+| `@justanarthur/payload-www/import-map-provider` | `setImportMapProvider`, `getImportMap` (stubs in the current build — reserved for future use) |
+
+There is **no root import** (`.`) and **no `/server`, `/with-www-config`, `/globals`, `/hooks`,
+`/render-utils`, `/render-components`, `/render-metadata`, `/components`, `/seed`, `/test`,
+`/data-seed`, `/data-test`, `/data-collections`** in the published exports — paths the previous
+README advertised that will fail at import time.
+
+## What the previous README got wrong
+
+For agents migrating from older docs:
+
+- `createWWWConfig({ locales, blocks })` → now `createWWWConfig()` (no args). Locales come from your
+  Payload `localization` config; `blocks` come from the `WWWInputConfig.blocks` field.
+- `defaultPlugins` callback → now `defaultPluginsConfigs: { seo, imageHash, translator, mcp }` map
+  on `WWWInputConfig`.
+- `createRevalidateCollectionHook({ collectionSlug, urlPathPrefix, … })` (CHANGELOG `[Unreleased]`)
+  → **not implemented yet**. The current hook is `createRevalidateCollectionGlobalHook()` (no args),
+  exported from `/collections`. Per-locale URL fan-out + `revalidatePath` does not happen — only
+  `revalidateTag` fires.
+- `createSitemapFile` → **not implemented**. The current export is `createSitemapFromCollections`,
+  used per-collection from your `app/(frontend)/sitemap.ts`.
+- `createPreviewHandler`, `LocaleSwitcher`, `LivePreviewListener`, `PageShowcase`, `HomePage`,
+  `createStaticPageExports`, `createStaticPagesCollection` → **none of these exist** as exports in
+  the current build. System pages render through a normal `createCollectionPageExports` mount (see
+  [Static pages](#static-pages-404--500--system) above).
+- `Pages / Posts slug` is `localized: true` by default — slug lives in `<collection>_locales`. Pass
+  `slugField({ localized: false })` to opt out per-collection.
 
 ## Building
 
 ```bash
 bun install
-bun run build      # produces dist/ via bunup
+bun run build      # bunup + scripts/strip-createRequire.mjs
 bun run typecheck  # tsc --noEmit
 bun run test       # vitest run
 ```
 
-The lib is built with the same `bunup` + `exports` plugin pattern as
-the monorepo's other plugins. One shim file per subpath under
-`src/exports/`, each re-exports from the implementation.
+The lib uses the same `bunup` + `src/exports/*` shim pattern as the sibling plugins. One shim file
+per subpath under `src/exports/`, each re-exporting from the implementation.
 
-## License
+## Licence
 
 MIT