@endora-commerce/mod-cms 0.0.0-stage → 0.100.0

package/dist/migrations/20260912T125709_cms_page_body_asset_ref_index.d.ts

@@ -0,0 +1,32 @@
+import { Migration } from '@mikro-orm/migrations';
+/**
+ * The GIN index on `cms_pages.body` that keeps the assets-library
+ * reference-protection scan fast (feature 013, research R10 — the reference
+ * registry's CMS descriptor runs `jsonb_path_exists` over `body`).
+ *
+ * It was created by `assets_library`' frozen
+ * `Migration20260505T102206AssetsLibraryInit` until
+ * `specs/120-migration-closure-bridge-ownership/` Phase 3. Under D-226 a
+ * migration may name a table only if its own module, its transitive
+ * `dependencies` closure or the platform creates it, and `assets_library`
+ * does not declare `cms` — nor could it sensibly, `cms` declaring
+ * `assets_library`. An instance that omits `cms` had `assets_library`'s init
+ * indexing a table nothing builds.
+ *
+ * It belongs here because `cms_pages` is this module's own table, and the
+ * closure holds in the direction the SQL runs: this module declares
+ * `assets_library`, not the other way round. The index exists for a
+ * consumer in another module and lives with the table it is on, which is
+ * what the ownership rule says.
+ *
+ * `if not exists`, because every database that has already applied the
+ * frozen migration has this index. The storage keys on the class name and
+ * holds no checksum, so the reduced frozen body is not re-offered there.
+ * The statement is otherwise the frozen one verbatim — same name, same
+ * operator class — so the two paths reach one schema.
+ */
+export declare class Migration20260912T125709CmsPageBodyAssetRefIndex extends Migration {
+    up(): Promise<void>;
+    down(): Promise<void>;
+}
+//# sourceMappingURL=20260912T125709_cms_page_body_asset_ref_index.d.ts.map

package/dist/migrations/20260912T125709_cms_page_body_asset_ref_index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"20260912T125709_cms_page_body_asset_ref_index.d.ts","sourceRoot":"","sources":["../../src/migrations/20260912T125709_cms_page_body_asset_ref_index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,uBAAuB,CAAC;AAElD;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,qBAAa,gDAAiD,SAAQ,SAAS;IAC9D,EAAE,IAAI,OAAO,CAAC,IAAI,CAAC;IAMnB,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;CAGrC"}

package/dist/migrations/20260912T125709_cms_page_body_asset_ref_index.js

@@ -0,0 +1,36 @@
+import { Migration } from '@mikro-orm/migrations';
+/**
+ * The GIN index on `cms_pages.body` that keeps the assets-library
+ * reference-protection scan fast (feature 013, research R10 — the reference
+ * registry's CMS descriptor runs `jsonb_path_exists` over `body`).
+ *
+ * It was created by `assets_library`' frozen
+ * `Migration20260505T102206AssetsLibraryInit` until
+ * `specs/120-migration-closure-bridge-ownership/` Phase 3. Under D-226 a
+ * migration may name a table only if its own module, its transitive
+ * `dependencies` closure or the platform creates it, and `assets_library`
+ * does not declare `cms` — nor could it sensibly, `cms` declaring
+ * `assets_library`. An instance that omits `cms` had `assets_library`'s init
+ * indexing a table nothing builds.
+ *
+ * It belongs here because `cms_pages` is this module's own table, and the
+ * closure holds in the direction the SQL runs: this module declares
+ * `assets_library`, not the other way round. The index exists for a
+ * consumer in another module and lives with the table it is on, which is
+ * what the ownership rule says.
+ *
+ * `if not exists`, because every database that has already applied the
+ * frozen migration has this index. The storage keys on the class name and
+ * holds no checksum, so the reduced frozen body is not re-offered there.
+ * The statement is otherwise the frozen one verbatim — same name, same
+ * operator class — so the two paths reach one schema.
+ */
+export class Migration20260912T125709CmsPageBodyAssetRefIndex extends Migration {
+    async up() {
+        this.addSql('create index if not exists "idx_cms_pages_body_asset_refs" on "cms_pages" using gin ("body" jsonb_path_ops);');
+    }
+    async down() {
+        this.addSql('drop index if exists "idx_cms_pages_body_asset_refs";');
+    }
+}
+//# sourceMappingURL=20260912T125709_cms_page_body_asset_ref_index.js.map

package/dist/migrations/20260912T125709_cms_page_body_asset_ref_index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"20260912T125709_cms_page_body_asset_ref_index.js","sourceRoot":"","sources":["../../src/migrations/20260912T125709_cms_page_body_asset_ref_index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,uBAAuB,CAAC;AAElD;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,MAAM,OAAO,gDAAiD,SAAQ,SAAS;IACpE,KAAK,CAAC,EAAE;QACf,IAAI,CAAC,MAAM,CACT,8GAA8G,CAC/G,CAAC;IACJ,CAAC;IAEQ,KAAK,CAAC,IAAI;QACjB,IAAI,CAAC,MAAM,CAAC,uDAAuD,CAAC,CAAC;IACvE,CAAC;CACF"}

package/dist/migrations/index.d.ts

@@ -0,0 +1,31 @@
+/**
+ * The `./migrations` subpath — every migration class this module owns, as one
+ * ordered `migrations` array.
+ *
+ * The array is what the platform reads when this module is **installed**:
+ * `src/packages/package-runtime.ts` takes `exported['migrations']` and refuses
+ * the package outright when it is absent (D-168).
+ *
+ * Listed in ascending timestamp, which is the order of this module's own
+ * migrations and of nothing else (feature 081): a manifest `dependencies` array
+ * is the only thing ordering this block against another module's.
+ *
+ * The **named** exports stay beside the array, and the asymmetry with
+ * `./backend` — which publishes an array and no named class (D-168) — is
+ * deliberate. `db/migrations-registry.generated.ts` imports each class by name
+ * from this specifier, and a migration class name is contract in a way an entity
+ * class name is not: `mikro_orm_migrations` persists it, so it is a string every
+ * already-migrated database holds.
+ *
+ * A class that is in neither the array nor the barrel is a migration that does
+ * not run: `migration:pending` reports nothing pending and the first symptom is
+ * a query against a table nobody created.
+ */
+import { Migration20260425T162418CmsPagesInit } from './20260425T162418_cms_pages_init.js';
+import { Migration20260505T130214CmsInit } from './20260505T130214_cms_init.js';
+import { Migration20260903T101741CmsNamespaceBlockNames } from './20260903T101741_cms_namespace_block_names.js';
+import { Migration20260912T094733CmsSalesChannelCmsPages } from './20260912T094733_cms_sales_channel_cms_pages.js';
+import { Migration20260912T125709CmsPageBodyAssetRefIndex } from './20260912T125709_cms_page_body_asset_ref_index.js';
+export declare const migrations: (typeof Migration20260425T162418CmsPagesInit)[];
+export { Migration20260425T162418CmsPagesInit, Migration20260505T130214CmsInit, Migration20260903T101741CmsNamespaceBlockNames, Migration20260912T094733CmsSalesChannelCmsPages, Migration20260912T125709CmsPageBodyAssetRefIndex, };
+//# sourceMappingURL=index.d.ts.map

package/dist/migrations/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/migrations/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,OAAO,EAAE,oCAAoC,EAAE,MAAM,qCAAqC,CAAC;AAC3F,OAAO,EAAE,+BAA+B,EAAE,MAAM,+BAA+B,CAAC;AAChF,OAAO,EAAE,8CAA8C,EAAE,MAAM,gDAAgD,CAAC;AAChH,OAAO,EAAE,+CAA+C,EAAE,MAAM,kDAAkD,CAAC;AACnH,OAAO,EAAE,gDAAgD,EAAE,MAAM,oDAAoD,CAAC;AAEtH,eAAO,MAAM,UAAU,iDAMtB,CAAC;AAEF,OAAO,EACL,oCAAoC,EACpC,+BAA+B,EAC/B,8CAA8C,EAC9C,+CAA+C,EAC/C,gDAAgD,GACjD,CAAC"}

package/dist/migrations/index.js

@@ -0,0 +1,37 @@
+/**
+ * The `./migrations` subpath — every migration class this module owns, as one
+ * ordered `migrations` array.
+ *
+ * The array is what the platform reads when this module is **installed**:
+ * `src/packages/package-runtime.ts` takes `exported['migrations']` and refuses
+ * the package outright when it is absent (D-168).
+ *
+ * Listed in ascending timestamp, which is the order of this module's own
+ * migrations and of nothing else (feature 081): a manifest `dependencies` array
+ * is the only thing ordering this block against another module's.
+ *
+ * The **named** exports stay beside the array, and the asymmetry with
+ * `./backend` — which publishes an array and no named class (D-168) — is
+ * deliberate. `db/migrations-registry.generated.ts` imports each class by name
+ * from this specifier, and a migration class name is contract in a way an entity
+ * class name is not: `mikro_orm_migrations` persists it, so it is a string every
+ * already-migrated database holds.
+ *
+ * A class that is in neither the array nor the barrel is a migration that does
+ * not run: `migration:pending` reports nothing pending and the first symptom is
+ * a query against a table nobody created.
+ */
+import { Migration20260425T162418CmsPagesInit } from './20260425T162418_cms_pages_init.js';
+import { Migration20260505T130214CmsInit } from './20260505T130214_cms_init.js';
+import { Migration20260903T101741CmsNamespaceBlockNames } from './20260903T101741_cms_namespace_block_names.js';
+import { Migration20260912T094733CmsSalesChannelCmsPages } from './20260912T094733_cms_sales_channel_cms_pages.js';
+import { Migration20260912T125709CmsPageBodyAssetRefIndex } from './20260912T125709_cms_page_body_asset_ref_index.js';
+export const migrations = [
+    Migration20260425T162418CmsPagesInit,
+    Migration20260505T130214CmsInit,
+    Migration20260903T101741CmsNamespaceBlockNames,
+    Migration20260912T094733CmsSalesChannelCmsPages,
+    Migration20260912T125709CmsPageBodyAssetRefIndex,
+];
+export { Migration20260425T162418CmsPagesInit, Migration20260505T130214CmsInit, Migration20260903T101741CmsNamespaceBlockNames, Migration20260912T094733CmsSalesChannelCmsPages, Migration20260912T125709CmsPageBodyAssetRefIndex, };
+//# sourceMappingURL=index.js.map

package/dist/migrations/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/migrations/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,OAAO,EAAE,oCAAoC,EAAE,MAAM,qCAAqC,CAAC;AAC3F,OAAO,EAAE,+BAA+B,EAAE,MAAM,+BAA+B,CAAC;AAChF,OAAO,EAAE,8CAA8C,EAAE,MAAM,gDAAgD,CAAC;AAChH,OAAO,EAAE,+CAA+C,EAAE,MAAM,kDAAkD,CAAC;AACnH,OAAO,EAAE,gDAAgD,EAAE,MAAM,oDAAoD,CAAC;AAEtH,MAAM,CAAC,MAAM,UAAU,GAAG;IACxB,oCAAoC;IACpC,+BAA+B;IAC/B,8CAA8C;IAC9C,+CAA+C;IAC/C,gDAAgD;CACjD,CAAC;AAEF,OAAO,EACL,oCAAoC,EACpC,+BAA+B,EAC/B,8CAA8C,EAC9C,+CAA+C,EAC/C,gDAAgD,GACjD,CAAC"}

package/docs/cms/extending-page-builder.md

@@ -0,0 +1,256 @@
+---
+title: Extending the Page Builder
+sidebar_position: 2
+---
+
+# Extending the Page Builder
+
+The CMS module ships built-in components — `Row`, `Columns`, `Text`,
+`Heading`, `Button`, `InsertBlock`, and others — but every other
+backend module can contribute its own components through an in-process
+service-provider interface (SPI). (`InsertTemplate` remains registered for
+legacy content trees but is no longer listed in the drawer palette.)
+A contributing module participates in three places:
+
+1. **Backend descriptor**: register field metadata at composition time so
+   the admin's component palette can render the editor controls.
+2. **Shared renderer**: ship a React component to a workspace package both
+   admin and storefront depend on (typically `@endora-commerce/cms-components` itself
+   or a per-module package re-exporting from it).
+3. **Composition wiring**: pass the contributing module's registration
+   helper to the platform's composition root before the CMS plugin is
+   instantiated.
+
+## 1. Declare the descriptor
+
+In your module's `plugin.ts` (or a dedicated `register-page-builder.ts`),
+declare a function that takes the registry and registers your components:
+
+```ts
+// the promotions module: src/backend/services/register-page-builder.ts
+import type { PageBuilderRegistry } from '../../cms/services/page-builder-registry.js';
+
+export function registerPromotionsPageBuilderComponents(
+  registry: PageBuilderRegistry,
+): void {
+  registry.register('promotions', {
+    components: {
+      PromoBanner: {
+        fields: {
+          headline: { type: 'text', label: 'Headline', required: true },
+          codeInput: { type: 'text', label: 'Promo code' },
+          tone: {
+            type: 'select',
+            label: 'Tone',
+            options: [
+              { label: 'Info', value: 'info' },
+              { label: 'Urgent', value: 'urgent' },
+            ],
+          },
+        },
+        previewIcon: 'ticket',
+        /** Omit email/invoice — this component is storefront-only. */
+        contexts: ['cms'],
+      },
+    },
+  });
+}
+```
+
+Field types are taken from the closed enum declared in
+`packages/contracts/src/cms.ts`: `text | textarea | number | select |
+radio | array | object | external | uuid | richtext`. This metadata is
+React-free; the backend never imports a renderer.
+
+## 2. Ship the renderer
+
+Add a React `ComponentConfig` in `packages/cms-components/src/components/`
+(or in your module's own admin/storefront package) and export it from the
+package's entry point:
+
+```tsx
+// packages/cms-components/src/components/PromoBanner.tsx
+import type { ComponentConfig } from '@measured/puck';
+
+interface Props {
+  headline: string;
+  codeInput?: string;
+  tone: 'info' | 'urgent';
+}
+
+export const PromoBanner: ComponentConfig<Props> = {
+  fields: {
+    headline: { type: 'text' },
+    codeInput: { type: 'text' },
+    tone: { type: 'select', options: [
+      { label: 'Info', value: 'info' },
+      { label: 'Urgent', value: 'urgent' },
+    ] },
+  },
+  defaultProps: { headline: 'Spring sale', tone: 'info' },
+  contexts: ['cms'],
+  render: ({ headline, codeInput, tone }) => (
+    <div className={`promo-banner promo-${tone}`}>
+      <strong>{headline}</strong>
+      {codeInput ? <code>{codeInput}</code> : null}
+    </div>
+  ),
+};
+```
+
+Wire it into the `defaultPageBuilderConfig` so both the admin editor and
+the storefront `<Render>` call sites pick it up:
+
+```ts
+// packages/cms-components/src/index.ts
+import { PromoBanner } from './components/PromoBanner.js';
+
+export * from './components/PromoBanner.js';
+
+export const defaultPageBuilderConfig = {
+  // ...existing categories
+  components: {
+    Row,
+    Columns,
+    Text,
+    Heading,
+    Button,
+    InsertBlock,
+    InsertTemplate,
+    PromoBanner,
+  },
+};
+```
+
+A renderer omitted from the bundle does not break the admin: the
+`PageBuilderEditor` merges the descriptor with the local config and
+substitutes a `MissingComponentPlaceholder` for any component the
+descriptor names but the bundle does not export. The placeholder renders
+nothing on the storefront unless the page is loaded with the
+`?cms_admin=1` query parameter (preview mode).
+
+## 3. Wire composition
+
+Call your registration helper from `composition.ts` before the CMS module
+is instantiated:
+
+```ts
+// backend/src/composition.ts
+const cms = cmsModule({ emFactory, requireAdmin });
+registerPromotionsPageBuilderComponents(cms.handle.pageBuilderRegistry);
+```
+
+The CMS module's plugin reads the registry on every
+`GET /api/v1/admin/cms/page-builder/config` call, so registering after the
+module instance is constructed is fine — the editor picks the new
+component up on the next admin reload.
+
+## Component name namespacing
+
+Component names are unique platform-wide. The registry warns and
+overwrites on collisions; reviewers should reject changes that produce a
+warning. By convention, prefix names with the contributing module's
+domain when ambiguity is likely (`PromoBanner`, `CatalogProductCard`,
+etc.).
+
+## Context availability (`contexts`)
+
+Every component declares which Page Builder surfaces may expose it via
+`contexts`:
+
+| Context | Used by |
+|---------|---------|
+| `cms` | CMS pages, blocks, templates, blog |
+| `email` | Transactional email editor |
+| `newsletter` | Newsletter campaigns (alias of email-safe set) |
+| `invoice` | Invoice PDF template editor |
+
+Register on the backend descriptor:
+
+```ts
+contexts: ['cms'], // default when omitted in registry — CMS-only
+```
+
+In `@endora-commerce/cms-components`, wrap the Puck config with
+`definePageBuilderComponent` from `@endora-commerce/page-builder-core` so the admin
+palette filter stays in sync. Components without `email` / `invoice` in
+`contexts` never appear in those editors (e.g. a product carousel).
+
+## Responsive props and visibility (CMS only)
+
+The CMS Page Builder supports per-breakpoint overrides with inheritance
+(mobile ← tablet ← desktop). Use `createResponsiveField` from
+`@endora-commerce/page-builder-core` for individual props and
+`withResponsiveVisibility` for a per-component **Visibility** control.
+
+Default breakpoints (configurable via Settings
+`cms.page_builder.breakpoint.*` or env `CMS_PB_BREAKPOINT_*`):
+
+- Mobile: &lt; 768px
+- Tablet: 768–1023px
+- Desktop: ≥ 1024px
+
+Email and invoice builders use a single layout width and do not expose
+responsive fields.
+
+**Email builders** (transactional + newsletter) do **not** use CMS Mobile /
+Tablet / Desktop viewports. The authoring canvas is fixed at **600px** (mail
+width). A **Preview** modal offers **600px** / **320px** HTML frames. Color
+fields reuse the CMS color palette.
+
+## Nesting (slots)
+
+Layout components (`Row`, `Columns`) use Puck **slot** fields — nested
+content is stored in `props`, not the legacy `zones` map.
+
+## Box model (CMS layout + content)
+
+Layout and content components expose **outer spacing** (margin), **inner
+spacing** (padding), and **border** fields on the Responsive tab. Values
+support uniform or per-side editing. **Columns** use a responsive column
+count (1–12 per breakpoint) with equal-width tracks.
+
+Use `createSpacingField`, `createBorderField`, and `createColorField` from
+`@endora-commerce/page-builder-core` when adding new CMS components.
+
+## Built-in Icons / Social
+
+- **`Icons`** — curated Lucide allowlist (~100 icons) in
+  `packages/cms-components/src/components/icon-catalog.ts` with a **visual
+  grid picker** (`IconPickerField`). Do not expose the full Lucide catalog.
+- **`Social`** — brand icons via `react-icons/fa6` (Facebook, X, Instagram,
+  LinkedIn, YouTube, TikTok, …). Array items use `getItemSummary` so the
+  selected **network name** appears in the Links list. Layouts:
+  `icons-only` | `icons-with-labels` | `vertical-list` | `pills`.
+
+## Additional landing components
+
+| Component | Purpose |
+| --------- | ------- |
+| `Spacer` | Vertical space + optional divider |
+| `FeatureList` | Icon + title + description columns |
+| `Hero` | Background + heading + CTA first-fold |
+| `LogoStrip` | Partner / trust logos |
+| `Testimonial` | Quote + author |
+| `Stats` | KPI strip |
+| `AnnouncementBar` | Thin promo strip |
+| `SimpleTable` | Pipe-separated headers/rows |
+| `NewsletterSignup` | Email form (wire `actionUrl` to newsletter) |
+| `ContactFormEmbed` | Iframe embed or mailto fallback |
+
+## Suggested follow-up (deeper integrations)
+
+| Priority | Idea | Why |
+| -------- | ---- | --- |
+| Medium | Newsletter ↔ module 048 | Auto-wire channel subscribe endpoint |
+| Low | Contact ↔ forms module | Pick an existing form instead of iframe URL |
+
+`Accordion` / `Tabs` already cover FAQ-style sections; prefer those before a
+dedicated FAQ component.
+
+## Testing
+
+The platform ships a TDD scaffold for the SPI in
+`backend/test/integration/cms/page-builder-extension.test.ts`. Use the
+fixture in `backend/test/fixtures/cms/test-extension-module.ts` as a
+template when adding tests for your own contributions.

package/docs/cms/index.md

@@ -0,0 +1,233 @@
+---
+title: CMS
+sidebar_position: 1
+description: Page Builder authoring surface — Pages, Blocks, Templates, Hooks — per channel + language
+---
+
+# CMS
+
+The CMS module is the platform's editorial surface. It owns four entities
+authored through a drag-and-drop **Page Builder** and surfaced on the
+storefront with full sales-channel and language scoping.
+
+| Entity      | Identifier        | Lifecycle                            | Embedded by                                   |
+| ----------- | ----------------- | ------------------------------------ | --------------------------------------------- |
+| **Page**    | `slug` (per channel) | `draft → published → archived`       | URL on the storefront                         |
+| **Block**   | `code` (per channel) | `active` flag                        | Pages (`InsertBlock`) and Hooks (attachment)  |
+| **Template**| `code` (per channel) | always-visible (no flag)             | Blueprints for pages/blocks (**Save as template** / **Apply template**). Legacy `InsertTemplate` embeds still resolve at runtime. |
+| **Hook**    | `code` (global)      | `active` flag, system-protected seed | Storefront layouts (`<Hook code="..." />`)    |
+
+## Entities and the reference graph
+
+The entity graph at runtime:
+
+```
+       Hook ──── attachment ────┐
+                                ▼
+                            Block ─── InsertBlock ───┐
+                                                     ▼
+                            Template (blueprint) ──> Page / Block canvas (Save as / Apply template)
+                            Template ── InsertTemplate (legacy) ──> Page (slug-routed)
+```
+
+Content templates (`cms_templates`) are reusable Page Builder layouts (Save as template / Apply template). Email and invoice templates stay in their own admin lists and storage. Embedding via `InsertTemplate` is withdrawn from the component drawer; existing trees still render.
+
+Reference protection runs on every delete:
+
+- A **Block** referenced by a Page, a Template, or a Hook attachment cannot be deleted (HTTP `409 CMS_REFERENCED`).
+- A **Template** referenced by a Page or a Block cannot be deleted.
+- A **Hook** flagged `is_system=true` cannot be deleted (`409 CMS_HOOK_SYSTEM_PROTECTED`); admin-created Hooks are deletable.
+
+Every reference scan is a JSONB walk over the entity's `content` envelope (`page→block`, `page→template`, `block→template`, `template→block`) plus a foreign-key check on `cms_hook_block_attachments` for `hook→block`.
+
+The same `content` JSONB is scanned by the **Assets Library reference registry** — deleting an Asset embedded in a CMS component's `props` is similarly refused.
+
+## Page Builder authoring
+
+The Page Builder is built on **Puck** (`@measured/puck`) and ships components
+in `@endora-commerce/cms-components`. Core layout/content defaults:
+
+| Component       | Purpose                                                                |
+| --------------- | ---------------------------------------------------------------------- |
+| `Row`           | Flex-column layout container.                                          |
+| `Heading`       | `h1`–`h6` with align + level select.                                   |
+| `Text`          | Simple body text with typography controls.                             |
+| `RichContent`   | TipTap rich text (links modal, colors, images).                        |
+| `Button`        | Label + link target + variant select.                                  |
+| `Image`         | URL or asset library; width modes + align.                             |
+| `Icons`         | Visual Lucide icon picker (~100 curated icons).                        |
+| `Social`        | Brand social icons (`react-icons`); link list shows network names.     |
+| `Spacer`        | Vertical spacing + optional divider.                                   |
+| `FeatureList`   | Icon + title + description columns.                                    |
+| `Hero`          | CTA banner with background, heading, button.                           |
+| `LogoStrip`     | Partner / trust logos.                                                 |
+| `Testimonial`   | Quote + author (+ optional avatar).                                    |
+| `Stats`         | KPI / counter strip.                                                   |
+| `AnnouncementBar` | Thin promo strip.                                                    |
+| `SimpleTable`   | Simple pipe-separated table.                                           |
+| `NewsletterSignup` | Email signup form (configurable action URL).                        |
+| `ContactFormEmbed` | Form iframe embed or mailto.                                        |
+| `InsertBlock`   | Embeds a Block by `code`. Storefront inlines the resolved Block.       |
+| `InsertTemplate`| Legacy: embeds a Template by `code`. Kept for existing trees; **not** in the drawer palette. Prefer Save as / Apply template. |
+
+Additional categories (catalog, media, interactive, forms, advanced) ship
+Product*, Video, Map, sliders, Tabs, Accordion, RawHtml/RawJs, etc.
+
+### Preview viewports
+
+Puck Mobile / Tablet / Desktop frames use logical widths **360 / tabletMin /
+max(desktopMin, 1280)**. Zoom is Puck’s built-in `transform: scale` inside an
+iframe (`waitForStyles: true`). Prefer the viewport switcher over browser
+resize when checking responsive props — CSS `@media` rules resolve against the
+iframe width, while editing-tier JS uses the selected viewport width.
+
+The content tree is persisted in a JSONB envelope:
+
+```jsonc
+{
+  "schema_version": 1,
+  "languages": {
+    "pl-PL": { /* Puck Data tree */ },
+    "en-US": { /* Puck Data tree */ }
+  }
+}
+```
+
+`schema_version` is bumped only when the storage shape of a node changes. The boot-time `content-schema-upgrader` walks every saved tree and rewrites nodes in place; current components start at `schema_version=1`.
+
+## Sales-channel + language scoping
+
+Every Page, Block, Template, and Hook is bound to one or more sales
+channels (M:N join with the `code`/`slug` denormalised onto the join row
+to enforce per-channel uniqueness at the DB level). The same `slug` may
+exist in two channels — they're independent rows. Languages live as a
+JSONB array on each entity; the storefront resolver follows the standard
+platform fallback rule (requested → channel default → 404).
+
+The admin's `ScopePicker` restricts the per-channel language list to
+each channel's configured language set; saving a Page whose `languages`
+includes a code unsupported by any assigned channel returns
+`400 CMS_LANGUAGE_NOT_IN_CHANNEL_SCOPE`.
+
+## Seeded Hooks
+
+23 base Hook codes are seeded with `is_system=true` at boot via an
+idempotent reconciler. They cover the standard storefront insertion
+points:
+
+```
+header.top
+homepage.top, homepage.bottom
+footer.before, footer.top, footer.bottom, footer.after, footer.copyright
+category.top, category.bottom
+product.top, product.bottom, product.buttons.after
+search.top, search.bottom
+page.top, page.bottom
+cms.page.top, cms.page.bottom
+login.top, login.bottom
+register.top, register.bottom
+```
+
+Each `<Hook code="…" />` server component fetches
+`/api/v1/cms/hooks/by-code` with the resolved channel + language and
+renders every active attached Block in `position` order. Empty
+attachments + failed fetches both render nothing — Hooks must not break a
+page render.
+
+## HTTP surface
+
+### Admin (`/api/v1/admin/cms`)
+
+| Method  | Path                                                | Purpose                                         |
+| ------- | --------------------------------------------------- | ----------------------------------------------- |
+| GET     | `/pages`                                            | Paginated Page list with filters.               |
+| POST    | `/pages`                                            | Create a Page (always starts as `draft`).       |
+| GET     | `/pages/:id`                                        | Detail with full content envelope + version.    |
+| PATCH   | `/pages/:id`                                        | Edit metadata; honours `If-Match` via `version`.|
+| PUT     | `/pages/:id/content/:language`                      | Save the Page Builder tree per language.        |
+| POST    | `/pages/:id/{publish,archive,unarchive}`            | Lifecycle transitions.                          |
+| DELETE  | `/pages/:id`                                        | Hard delete (channels are cascade-unbound).     |
+| Same    | `/blocks/*`                                         | Same shape; per-channel-unique `code`; reference-protected on delete. |
+| Same    | `/templates/*`                                      | Same shape minus `active` flag.                 |
+| GET     | `/hooks`, `/hooks/:id`                              | List + detail with attachment count.            |
+| POST    | `/hooks`                                            | Create an admin (non-system) Hook.              |
+| PATCH   | `/hooks/:id`                                        | Edit name / active / scope; `code` is immutable.|
+| DELETE  | `/hooks/:id`                                        | Refused with 409 when `is_system=true`.         |
+| GET / POST / PATCH / DELETE | `/hooks/:id/attachments[/:blockId]` | Attach / reorder / detach Blocks on a Hook.     |
+| GET     | `/page-builder/config`                              | Merged Page Builder descriptor (metadata only). |
+
+### Storefront (`/api/v1/cms`)
+
+| Method | Path                              | Returns                                                        |
+| ------ | --------------------------------- | -------------------------------------------------------------- |
+| GET    | `/pages/by-slug?slug=…&language=…`| Resolved Page with `embeds.blocks`, `embeds.templates`, assets.|
+| GET    | `/blocks/by-code?code=…&language=…`| Resolved Block (single, channel-filtered, active-only).       |
+| GET    | `/hooks/by-code?code=…&language=…`| Ordered active Block list for the named Hook.                  |
+
+Channel resolution prefers the `X-Sales-Channel` header, then falls back
+to the system-default channel. Language resolution prefers `?language=`,
+then `Accept-Language`, then the channel's configured default.
+
+## Storefront resolution + Redis cache
+
+The single `StorefrontResolver` service answers all three storefront
+read operations with one query for the root entity, one batched query
+per embed type (`InsertBlock` / `InsertTemplate`) per recursion level,
+and one batched call to `assetsLibrary.resolveUrl` for every embedded
+asset. Recursion is capped at depth 3; cycles or deeper graphs degrade
+to a `MissingComponentPlaceholder` rendered admin-side.
+
+Resolved payloads are cached in Redis with a 5-minute TTL under three
+key families:
+
+```
+cms:v1:page:<slug>:<channel>:<language>
+cms:v1:block:<code>:<channel>:<language>
+cms:v1:hook:<code>:<channel>:<language>
+```
+
+Invalidation runs on every Page / Block / Template / Hook write:
+
+- Page write → drops `cms:v1:page:<slug>:*` for every slug the page is bound to.
+- Block write → drops the block's own keys + every page-keyed entry (we don't yet track which pages embed which block; coarse drop is acceptable at platform scale).
+- Template write → drops every CMS-namespace key.
+- Hook / attachment write → drops the hook's keys.
+
+Performance target: page resolution with 5 embedded Blocks + 3 embedded
+Templates returns in &lt; 200 ms p95 cold; warm path returns in &lt; 5 ms.
+
+## Migration from legacy `cms_pages`
+
+Previously, `cms_pages` carried `path` + `body` (per-language HTML) and a
+`status` enum. Migration `035_cms_init.ts` adds the new column set
+(`slug`, `name`, `active`, `content`, `languages`, `version`, `meta_*`)
+and backfills every row idempotently:
+
+- `slug = path`
+- `name = title['en-US']` (best effort)
+- `active = (status = 'published')`
+- `content` envelope built from `body` with each language's HTML wrapped in a single `Text` node carrying `tiptapHtml`
+- `languages` array = non-empty body keys
+- bound to the platform's default sales channel via `cms_page_sales_channels`
+
+Re-running the backfill against a partially-migrated state is a no-op.
+The legacy `path`, `title`, and `body` columns survive for one release as
+mirrors; the asset-ref scan covers `body` for backward compatibility.
+
+## Extending the Page Builder
+
+Other backend modules contribute components via the SPI in
+`packages/modules/cms/src/backend/services/page-builder-registry.ts`. See the
+[Extending the Page Builder](./extending-page-builder) guide for the
+end-to-end workflow: descriptor declaration, renderer shipping, and
+composition wiring.
+
+## Error codes
+
+`CMS_PAGE_NOT_FOUND`, `CMS_BLOCK_NOT_FOUND`, `CMS_TEMPLATE_NOT_FOUND`,
+`CMS_HOOK_NOT_FOUND`, `CMS_SLUG_CONFLICT`, `CMS_CODE_CONFLICT`,
+`CMS_REFERENCED`, `CMS_HOOK_SYSTEM_PROTECTED`,
+`CMS_LANGUAGE_NOT_IN_CHANNEL_SCOPE`, `CMS_SCHEMA_UPGRADE_FAILED`.
+
+All envelopes follow the platform-wide error contract in
+`packages/contracts/src/errors.ts`.