@endora-commerce/mod-cms 0.102.0 → 0.103.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -10,17 +10,19 @@ The CMS module ships built-in components — `Row`, `Columns`, `Text`,
10
10
  backend module can contribute its own components. (`InsertTemplate` remains
11
11
  registered for legacy content trees but is no longer listed in the drawer
12
12
  palette.) The `cms`, `catalog`, `orders`, `invoices` and `transactional_emails`
13
- modules already contribute blocks this way. A contributing module participates in two
14
- places:
13
+ modules already declare their blocks this way. Their renderers are still the
14
+ built-in ones in `@endora-commerce/cms-components` and
15
+ `@endora-commerce/email-components`; a module package outside the platform
16
+ ships its own, as section 2 describes. A contributing module participates in
17
+ two places:
15
18
 
16
19
  1. **Manifest declaration**: declare the block's metadata — name, labels,
17
20
  palette category, contexts and editable fields — in the module's own
18
21
  `manifest.ts`. The CMS module builds its Page Builder registry from the
19
22
  manifests of the composed modules, so there is no registration call to
20
23
  write.
21
- 2. **Shared renderer**: ship a React component to a workspace package both
22
- admin and storefront depend on (typically `@endora-commerce/cms-components` itself
23
- or a per-module package re-exporting from it).
24
+ 2. **Renderers**: ship, in the module's own package, the code that draws the
25
+ block on the storefront, in e-mail and in the admin editors.
24
26
 
25
27
  ## 1. Declare the block in the manifest
26
28
 
@@ -64,7 +66,8 @@ export const manifest = defineModuleManifest({
64
66
  ```
65
67
 
66
68
  The schema is `BlockDefinitionSchema` and `BlockCategorySchema` in
67
- `packages/contracts/src/cms.ts`. `defineModuleManifest` refuses a manifest
69
+ `packages/contracts/src/cms.ts` (both exported from
70
+ `@endora-commerce/contracts`). `defineModuleManifest` refuses a manifest
68
71
  that breaks either of two rules:
69
72
 
70
73
  - A block `name` is `<module id>.<PascalCaseName>`, and the part before the
@@ -89,71 +92,525 @@ declarations by module presence when it answers
89
92
  `GET /api/v1/admin/cms/page-builder/config`, so a module that is switched off
90
93
  takes its blocks out of the palette with it.
91
94
 
92
- ## 2. Ship the renderer
95
+ ## 2. Ship the renderers
96
+
97
+ A module package draws its own blocks. It does so through up to three
98
+ **layers**, one per process that renders a block, plus an optional stylesheet.
99
+ Each is a subpath of the package's `exports` map, and each is optional: a
100
+ module whose blocks are e-mail-only ships the e-mail layer and nothing else.
101
+
102
+ | Subpath | What it exports | Who renders with it |
103
+ | --- | --- | --- |
104
+ | `./storefront` | `contributions` — React renderers for the module's `cms` blocks | the storefront, in the server-rendered HTML |
105
+ | `./email` | `emailBlocks` — pure functions that render the module's `email` blocks to HTML and text | the backend when it sends, and the admin's e-mail editor |
106
+ | `./admin` | `contributions.blocks` — editor renderers, beside the module's routes and zones | the admin's CMS and e-mail editors |
107
+ | `./blocks.css` | one finished stylesheet | the storefront and the admin editor |
108
+
109
+ This is for a module **package** — one a storefront and an instance install
110
+ from a registry. The platform's own modules do not ship these layers yet: their
111
+ `package.json` is generated, and the generator does not render the three
112
+ subpaths. An overlay module has no package; its blocks are covered under
113
+ [A block no package renders](#a-block-no-package-renders).
114
+
115
+ The examples below quote the platform's own acceptance fixture: a module
116
+ outside every platform package that ships all three layers and a stylesheet
117
+ for one block, `acceptance_blocks.Badge`.
118
+
119
+ ### The package
120
+
121
+ A surface finds the package by its own `package.json`:
122
+
123
+ <!-- verbatim-from: backend/acceptance/block-renderers-fixture/package.json -->
124
+ ```json
125
+ "files": [
126
+ "dist",
127
+ "i18n",
128
+ "blocks.css",
129
+ "tailwind.css"
130
+ ],
131
+ "endora": {
132
+ "type": "module",
133
+ "id": "acceptance_blocks"
134
+ },
135
+ "exports": {
136
+ ".": {
137
+ "types": "./dist/manifest.d.ts",
138
+ "default": "./dist/manifest.js"
139
+ },
140
+ "./backend": {
141
+ "types": "./dist/backend/index.d.ts",
142
+ "default": "./dist/backend/index.js"
143
+ },
144
+ "./admin": {
145
+ "types": "./dist/admin/index.d.ts",
146
+ "default": "./dist/admin/index.js"
147
+ },
148
+ "./storefront": {
149
+ "types": "./dist/storefront/index.d.ts",
150
+ "default": "./dist/storefront/index.js"
151
+ },
152
+ "./email": {
153
+ "types": "./dist/email/index.d.ts",
154
+ "default": "./dist/email/index.js"
155
+ },
156
+ "./blocks.css": "./blocks.css",
157
+ "./tailwind.css": "./tailwind.css",
158
+ "./i18n/*": "./i18n/*",
159
+ "./package.json": "./package.json"
160
+ ```
161
+
162
+ - **`endora.type` must be `module`, and `endora.id` the module id** that
163
+ prefixes its block names. A package without that block is not a module
164
+ package: `blocks:generate` says so in a note and registers nothing from it,
165
+ and its blocks render as placeholders.
166
+ - **`files` lists everything an `exports` entry points at** — `blocks.css` and
167
+ `tailwind.css` beside `dist`. An entry whose file is not in the tarball is
168
+ refused by the generator that would import it.
169
+ - **Each layer publishes type declarations** beside its JavaScript (the `types`
170
+ condition above). A storefront written in TypeScript imports `./storefront`
171
+ from its generated registry, and `blocks:generate` refuses a storefront layer
172
+ that ships none as `untyped-layer`.
173
+ - **A package with `./admin` also publishes `./tailwind.css`**, which tells the
174
+ admin's Tailwind build where the layer is. `endora generate` refuses an admin
175
+ layer without it. The fixture's is one line, quoted below the list.
176
+ - **The layers' imports are peer dependencies**: `@endora-commerce/contracts`,
177
+ `@endora-commerce/page-builder-core`, `@endora-commerce/email-components`,
178
+ `@puckeditor/core` and `react`, with `@endora-commerce/platform` for the
179
+ backend.
180
+ - **The build is plain `tsc`**, which keeps a leading `'use client'` and emits
181
+ the declarations. Relative imports are written with the `.js` extension.
182
+
183
+ <!-- verbatim-from: backend/acceptance/block-renderers-fixture/tailwind.css -->
184
+ ```css
185
+ @source "./dist/admin";
186
+ ```
187
+
188
+ Where the names in the examples come from:
189
+
190
+ | Name | Import it from |
191
+ | --- | --- |
192
+ | `StorefrontContributions`, `PageBuilderBlockEditorConfig`, `useBlockRenderEnvironment` | `@endora-commerce/page-builder-core/contributions` |
193
+ | `sanitizeRichHtml` | `@endora-commerce/cms-components` |
194
+ | `EmailBlockRenderers` | `@endora-commerce/email-components/render/block-renderers` |
195
+ | `escapeHtml`, `escapeAttr` | `@endora-commerce/email-components/render/escape-html` |
196
+ | `AdminContributions`, `EmailBlockRendererRegistryPort` | `@endora-commerce/contracts` |
197
+ | `ModuleContext`, `lazyPort` | `@endora-commerce/platform/kernel` |
198
+
199
+ ### The declaration the layers draw
200
+
201
+ The block is declared in the module's manifest, for both contexts it is drawn
202
+ in, in a palette section the same manifest declares for both:
203
+
204
+ <!-- verbatim-from: backend/acceptance/block-renderers-fixture/src/manifest.ts -->
205
+ ```ts
206
+ blockCategories: [
207
+ { key: 'acceptance', titleKey: 'blocks.section', contexts: ['cms', 'email'], weight: 900 },
208
+ ],
209
+ blocks: [
210
+ {
211
+ // The persisted name — `<endora.id>.<Name>`, and permanent. Written as a
212
+ // literal: `endora check` reads a block's name and contexts off the
213
+ // manifest's text, and a name it cannot read is one it cannot hold a
214
+ // renderer to.
215
+ name: 'acceptance_blocks.Badge',
216
+ labelKey: 'blocks.badge.label',
217
+ descriptionKey: 'blocks.badge.description',
218
+ category: 'acceptance',
219
+ contexts: ['cms', 'email'],
220
+ fields: {
221
+ text: { type: 'text', label: 'Text' },
222
+ // Forces every renderer of this block to throw. It exists for the
223
+ // failure-isolation assertion and for nothing an operator would use.
224
+ explode: {
225
+ type: 'radio',
226
+ label: 'Fail on render',
227
+ options: [
228
+ { label: 'No', value: 'no' },
229
+ { label: 'Yes', value: 'yes' },
230
+ ],
231
+ },
232
+ },
233
+ defaultProps: { text: 'New badge', explode: 'no' },
234
+ weight: 10,
235
+ },
236
+ ],
237
+ ```
238
+
239
+ Every renderer is keyed by the block's full name, and a package renders only
240
+ the blocks **its own manifest declares**, for a context that block declares:
241
+ `cms` for the storefront and the CMS editor, `email` for e-mail. Write the name
242
+ and the contexts as literals, in the manifest and in each layer:
243
+ `check:block-renderers` reads them off the source text, and a name it cannot
244
+ read is one it cannot hold a renderer to. A computed renderer key escapes the
245
+ check and is refused when the surface composes it.
246
+
247
+ ### The storefront layer
248
+
249
+ `src/storefront/index.ts` exports `contributions`, a map from block name to a
250
+ Puck component config:
251
+
252
+ <!-- verbatim-from: backend/acceptance/block-renderers-fixture/src/storefront/index.ts -->
253
+ ```ts
254
+ import type { StorefrontContributions } from '@endora-commerce/page-builder-core/contributions';
93
255
 
94
- Add a React `ComponentConfig` in `packages/cms-components/src/components/`
95
- (or in your module's own admin/storefront package) and export it from the
96
- package's entry point:
256
+ import { Badge } from './Badge.js';
97
257
 
258
+ export const contributions: StorefrontContributions = {
259
+ blocks: {
260
+ 'acceptance_blocks.Badge': {
261
+ defaultProps: { text: 'New badge', explode: 'no' },
262
+ render: Badge,
263
+ },
264
+ },
265
+ };
266
+ ```
267
+
268
+ The renderer is an ordinary React component. Its props are the block's stored
269
+ props, with the `defaultProps` above filled in underneath them — so a prop the
270
+ module added after a page was saved still has a value:
271
+
272
+ <!-- verbatim-from: backend/acceptance/block-renderers-fixture/src/storefront/Badge.tsx -->
98
273
  ```tsx
99
- // packages/cms-components/src/components/PromoBanner.tsx
100
- import type { ComponentConfig } from '@puckeditor/core';
274
+ 'use client';
275
+
276
+ import { useBlockRenderEnvironment } from '@endora-commerce/page-builder-core/contributions';
277
+ import type { ReactNode } from 'react';
278
+
279
+ export interface BadgeProps {
280
+ readonly text?: string;
281
+ readonly explode?: string | boolean;
282
+ }
283
+
284
+ /**
285
+ * The renderer's one built-in string — a label that is not operator content —
286
+ * shipped in both languages inside the layer and chosen by the request's
287
+ * content language, with English as the fallback. The storefront's own
288
+ * catalogue belongs to the storefront's owner.
289
+ */
290
+ const LABEL: Readonly<Record<string, string>> = { en: 'Badge', pl: 'Odznaka' };
291
+
292
+ /**
293
+ * Synchronous, reads no browser global, and draws the same output on the
294
+ * server and on hydration for the same props: it is part of the
295
+ * server-rendered HTML.
296
+ */
297
+ export function Badge({ text, explode }: BadgeProps): ReactNode {
298
+ const { language } = useBlockRenderEnvironment();
299
+ if (explode === true || explode === 'yes') {
300
+ throw new Error('acceptance_blocks.Badge was asked to fail on render');
301
+ }
302
+ const label = LABEL[language.slice(0, 2).toLowerCase()] ?? LABEL['en'];
303
+ return (
304
+ <span className="acceptance_blocks-badge" title={label}>
305
+ {`acceptance-badge:${String(text ?? '')}`}
306
+ </span>
307
+ );
308
+ }
309
+ ```
310
+
311
+ A storefront renderer runs once on the server and once in the browser, so:
312
+
313
+ - it is **synchronous** — no `async` component — and reads no browser global
314
+ (`window`, `document`, `localStorage`) while rendering, only in an effect;
315
+ - it draws the same output on the server and in the browser for the same
316
+ props: no `Date.now()`, no `Math.random()`, no locale-dependent formatting
317
+ without the language from `useBlockRenderEnvironment()`;
318
+ - every file of the layer starts with `'use client'`. `check:block-renderers`
319
+ does not hold this one; a layer without it fails the storefront's build;
320
+ - it imports only `react`, `react-dom`, `@puckeditor/core`,
321
+ `@endora-commerce/page-builder-core`, `@endora-commerce/cms-components`,
322
+ `@endora-commerce/contracts` and its own files. Nothing server-only, no
323
+ admin kit, no platform, no other module. Data it needs comes from its props,
324
+ from the CMS render context, or from a fetch in an effect;
325
+ - block props are **untrusted input**: HTML is injected only as
326
+ `dangerouslySetInnerHTML={{ __html: sanitizeRichHtml(value) }}`;
327
+ - a label the renderer prints itself — one that is not the operator's content —
328
+ ships in English and Polish inside the layer and is chosen by
329
+ `useBlockRenderEnvironment().language`, with English as the fallback.
330
+
331
+ **Installing it in a storefront.** A storefront owner adds the package to
332
+ their storefront (`pnpm add`) and builds. `blocks:generate`, which the `dev`
333
+ and `build` scripts of a storefront created by release `0.103.0` or later run,
334
+ finds every installed module package that declares `./storefront` or
335
+ `./blocks.css` and writes the registry and the stylesheet import — there is no
336
+ line to add to any file.
337
+
338
+ **A storefront created by an earlier release has none of this, and upgrading
339
+ does not add it.** An upgrade moves a storefront's packages and leaves its
340
+ source as it was written, so such a storefront has no `blocks:generate`
341
+ script, no `lib/page-builder/` and no presence rule: a package's storefront
342
+ layer is not rendered there, and neither *A block no package renders* nor the
343
+ storefront row of *When the module is switched off* below applies to it, until
344
+ its owner brings the files over by hand. The steps are in the *Upgrading an
345
+ instance* guide, under *Module blocks in an existing storefront*.
346
+
347
+ When `endora install` writes an instance and a storefront in one run, it adds
348
+ the instance's modules that publish a storefront layer to the storefront's
349
+ dependencies, once. No platform module publishes one yet, so a default install
350
+ adds nothing; a package added to the instance afterwards is added to the
351
+ storefront by its owner.
352
+
353
+ What `blocks:generate` refuses, writing nothing and exiting 1:
354
+
355
+ | Refusal | Meaning |
356
+ | --- | --- |
357
+ | `untyped-layer` | the package publishes `./storefront` with no type declarations |
358
+ | `missing-layer-file` | an `exports` entry points at a file the package does not hold |
359
+ | `layer-without-subpath` | the package ships `src/storefront/index.ts` and declares no `./storefront` |
360
+ | `duplicate-module` | two installed packages declare the same module id |
361
+
362
+ #### A block no package renders
363
+
364
+ A storefront can also render a block itself — typically one an overlay module
365
+ of its own instance declares — by adding it to
366
+ `lib/page-builder/local-blocks.tsx`, the one file of the block registry that is
367
+ the storefront owner's. A local block never replaces a block a package or the
368
+ platform already renders.
369
+
370
+ ### The e-mail layer
371
+
372
+ `src/email/index.ts` exports `emailBlocks`. Each renderer is a pure function —
373
+ no React, no I/O — that returns rows of the e-mail's table layout and escapes
374
+ every prop:
375
+
376
+ <!-- verbatim-from: backend/acceptance/block-renderers-fixture/src/email/index.ts -->
377
+ ```ts
378
+ import type { EmailBlockRenderers } from '@endora-commerce/email-components/render/block-renderers';
379
+ import { escapeHtml } from '@endora-commerce/email-components/render/escape-html';
101
380
 
102
- interface Props {
103
- headline: string;
104
- codeInput?: string;
105
- tone: 'info' | 'urgent';
381
+ interface BadgeProps {
382
+ readonly text?: string;
383
+ readonly explode?: string | boolean;
106
384
  }
107
385
 
108
- export const PromoBanner: ComponentConfig<Props> = {
109
- fields: {
110
- headline: { type: 'text' },
111
- codeInput: { type: 'text' },
112
- tone: { type: 'select', options: [
113
- { label: 'Info', value: 'info' },
114
- { label: 'Urgent', value: 'urgent' },
115
- ] },
386
+ function assertRenderable(props: BadgeProps): void {
387
+ if (props.explode === true || props.explode === 'yes') {
388
+ throw new Error('acceptance_blocks.Badge was asked to fail on render');
389
+ }
390
+ }
391
+
392
+ export const emailBlocks: EmailBlockRenderers = {
393
+ 'acceptance_blocks.Badge': {
394
+ defaultProps: { text: 'New badge' },
395
+ html: (props: BadgeProps, ctx) => {
396
+ assertRenderable(props);
397
+ return (
398
+ '<tr><td style="padding:8px 24px;font-family:Arial,Helvetica,sans-serif;">' +
399
+ `<span style="display:inline-block;padding:4px 10px;border-radius:6px;background-color:${ctx.accentColor};color:#ffffff;font-size:14px;font-weight:bold;">` +
400
+ `acceptance-badge:${escapeHtml(String(props.text ?? ''))}` +
401
+ '</span></td></tr>'
402
+ );
403
+ },
404
+ text: (props: BadgeProps) => {
405
+ assertRenderable(props);
406
+ return `acceptance-badge:${String(props.text ?? '')}\n`;
407
+ },
116
408
  },
117
- defaultProps: { headline: 'Spring sale', tone: 'info' },
118
- contexts: ['cms'],
119
- render: ({ headline, codeInput, tone }) => (
120
- <div className={`promo-banner promo-${tone}`}>
121
- <strong>{headline}</strong>
122
- {codeInput ? <code>{codeInput}</code> : null}
123
- </div>
124
- ),
125
409
  };
126
410
  ```
127
411
 
128
- Wire it into the `defaultPageBuilderConfig` under the block's full name, so
129
- both the admin editor and the storefront `<Render>` call sites pick it up:
412
+ `text` is optional; without it the plain-text part is derived from the HTML.
413
+ The second argument carries `accentColor`, the message's `language` — a label
414
+ the renderer prints itself follows it, as on the storefront — and
415
+ `renderSlot(nodes)`, which renders nested content with the platform's own
416
+ renderer. `{{var …}}` directives in the output are resolved afterwards,
417
+ exactly as in a built-in block. The layer imports only
418
+ `@endora-commerce/email-components/render/*`, `@endora-commerce/contracts` and
419
+ its own files, because the same function runs in the backend and in the
420
+ admin's browser.
421
+
422
+ The module's backend registers the renderers when the platform boots, and its
423
+ manifest names `email` in `dependencies`:
130
424
 
425
+ <!-- verbatim-from: backend/acceptance/block-renderers-fixture/src/manifest.ts -->
131
426
  ```ts
132
- // packages/cms-components/src/index.ts
133
- import { PromoBanner } from './components/PromoBanner.js';
134
-
135
- export const defaultPageBuilderConfig: Config = {
136
- components: {
137
- // ...the existing 'cms.*' and 'catalog.*' entries
138
- 'promotions.PromoBanner': definePageBuilderComponent({
139
- ...(PromoBanner as unknown as ComponentConfig),
140
- contexts: ['cms'],
141
- }),
142
- },
427
+ // `email` owns the registry this module registers its e-mail renderer into.
428
+ // It is non-deactivatable, so the edge never fails closed.
429
+ dependencies: ['email'],
430
+ ```
431
+
432
+ <!-- verbatim-from: backend/acceptance/block-renderers-fixture/src/backend/index.ts -->
433
+ ```ts
434
+ import type { EmailBlockRendererRegistryPort } from '@endora-commerce/contracts';
435
+ import { lazyPort, type ModuleContext } from '@endora-commerce/platform/kernel';
436
+
437
+ import { emailBlocks } from '../email/index.js';
438
+
439
+ /** This module persists nothing. */
440
+ export const entities = [] as const;
441
+
442
+ export function registerModule(ctx: ModuleContext): void {
443
+ // From a boot hook, unprobed: the registry is ungated and decides presence
444
+ // itself, per render, on the contributor recorded here — so switching this
445
+ // module off, or back on, needs no restart and no re-registration.
446
+ ctx.onBoot(() => {
447
+ lazyPort<EmailBlockRendererRegistryPort>(ctx, 'emailBlockRendererRegistry').register(
448
+ 'acceptance_blocks',
449
+ emailBlocks,
450
+ );
451
+ });
452
+ }
453
+ ```
454
+
455
+ `register` never throws. A name the module does not own, or an entry without an
456
+ `html` function, is refused with a warning in the backend log and listed in the
457
+ `refused` array the call returns — assert on that array in a test.
458
+
459
+ Transactional e-mail and newsletter campaigns both render through that
460
+ registry, and content holding the block can be saved in either. A built-in
461
+ e-mail block cannot be overridden: a contributed renderer is consulted only for
462
+ a name the platform does not draw itself.
463
+
464
+ ### The admin layer
465
+
466
+ The module's `./admin` layer — the one that already declares its routes and
467
+ zone contributions — lists an editor renderer per block and editor:
468
+
469
+ <!-- verbatim-from: backend/acceptance/block-renderers-fixture/src/admin/index.ts -->
470
+ ```ts
471
+ import type { AdminContributions } from '@endora-commerce/contracts';
472
+
473
+ export const contributions: AdminContributions = {
474
+ blocks: [
475
+ {
476
+ name: 'acceptance_blocks.Badge',
477
+ context: 'cms',
478
+ component: () => import('./badge-editor.js'),
479
+ },
480
+ {
481
+ name: 'acceptance_blocks.Badge',
482
+ context: 'email',
483
+ component: () => import('./badge-email.js'),
484
+ },
485
+ ],
143
486
  };
144
487
  ```
145
488
 
146
- The CMS renderers are this one bundle (e-mail blocks render from
147
- `@endora-commerce/email-components` the same way). A module published
148
- outside this repository cannot add a renderer to either bundle without a
149
- change to that package.
489
+ For the CMS editor the default export is the block's renderer — usually the
490
+ storefront's own component, so the canvas shows what the storefront draws:
491
+
492
+ <!-- verbatim-from: backend/acceptance/block-renderers-fixture/src/admin/badge-editor.tsx -->
493
+ ```tsx
494
+ import type { PageBuilderBlockEditorConfig } from '@endora-commerce/page-builder-core/contributions';
495
+
496
+ import { Badge } from '../storefront/Badge.js';
497
+
498
+ const editor: PageBuilderBlockEditorConfig = { render: Badge };
499
+
500
+ export default editor;
501
+ ```
502
+
503
+ For the e-mail editor it is the e-mail layer's renderer, the function the send
504
+ path runs, so the canvas and the preview cannot differ from the message:
505
+
506
+ <!-- verbatim-from: backend/acceptance/block-renderers-fixture/src/admin/badge-email.ts -->
507
+ ```ts
508
+ import { emailBlocks } from '../email/index.js';
509
+
510
+ export default emailBlocks['acceptance_blocks.Badge'];
511
+ ```
512
+
513
+ The block's label, palette section, default props and field set come from the
514
+ manifest declaration, not from the contribution. A CMS editor config may carry
515
+ `fields` to replace the editor of a field the manifest declares — a picker in
516
+ place of a text input — and cannot add a field the manifest does not declare.
517
+
518
+ A declared block with **no** editor renderer is still insertable and editable:
519
+ the editor builds its fields from the manifest declaration and shows a neutral
520
+ preview that names the block. That is what an overlay module's block gets,
521
+ since an overlay module has no admin layer. In the e-mail editor such a block
522
+ is also absent from the HTML preview, although the backend renders it in the
523
+ message that is sent.
524
+
525
+ **Installing it in an instance.** The instance's owner adds the package to the
526
+ instance's dependencies and installs. Then:
527
+
528
+ 1. `pnpm run build:admin` — it runs `endora generate`, which names the
529
+ package's `./admin` in the admin's contribution registry and its
530
+ `./blocks.css` in the admin's stylesheet, and then builds the admin.
531
+ 2. `pnpm run module:install <module id>` — the module's lifecycle install,
532
+ which creates the Setting an operator switches it on and off with.
533
+ 3. Restart the backend. Its e-mail renderers are registered at boot.
534
+
535
+ There is no line to add to any file of the instance.
536
+
537
+ ### The block stylesheet
538
+
539
+ `./blocks.css` is one finished stylesheet. Every selector is under a class
540
+ prefixed with the module id, and colours and fonts come from the storefront's
541
+ theme custom properties with literal fallbacks, so the block follows the
542
+ channel's theme and still renders on the admin canvas:
543
+
544
+ <!-- verbatim-from: backend/acceptance/block-renderers-fixture/blocks.css -->
545
+ ```css
546
+ .acceptance_blocks-badge {
547
+ display: inline-block;
548
+ padding: 0.25rem 0.625rem;
549
+ border-radius: var(--r-md, 6px);
550
+ background: var(--brand-600, #2563eb);
551
+ color: #ffffff;
552
+ font-family: var(--font-sans, system-ui, sans-serif);
553
+ font-size: 0.875rem;
554
+ font-weight: 600;
555
+ line-height: 1.4;
556
+ }
557
+ ```
558
+
559
+ No `@import`, no `@tailwind`, no `@source`, no element selectors. The
560
+ storefront imports it through `blocks:generate` and the admin through
561
+ `endora generate`.
562
+
563
+ ### When the module is switched off
564
+
565
+ A block whose module an operator switched off is absent on every surface, and
566
+ nothing is written to the stored content:
567
+
568
+ | Surface | What happens |
569
+ | --- | --- |
570
+ | Storefront | the block renders nothing to a customer; with `?cms_admin=1` it renders a note naming the block |
571
+ | E-mail | the block contributes nothing to the HTML or the text; the message is still sent, and content holding the block can still be saved |
572
+ | Admin editors | a stored block is a visible placeholder that keeps its props; the block is not offered in the palette |
573
+
574
+ Switching the module back on restores all three, with no document changed in
575
+ between. The storefront decides from the modules the backend **reports** as not
576
+ present, so a block whose owner the backend does not know — an overlay
577
+ module's — still renders. The same holds for a package the storefront has
578
+ installed and the backend does not compose, and when the backend cannot be
579
+ reached nobody is reported absent.
580
+
581
+ ### When a renderer fails
582
+
583
+ A renderer that throws costs the page that one block. On the storefront and in
584
+ the editors it becomes the same placeholder a missing renderer gets, and the
585
+ blocks around it are untouched; in an e-mail it contributes nothing, the
586
+ message is still sent, and the failure is logged with the block and its
587
+ module.
588
+
589
+ ### Check the package
590
+
591
+ Run the check in the module package:
592
+
593
+ ```bash
594
+ pnpm exec endora check --rule check:block-renderers
595
+ ```
596
+
597
+ | Finding | Meaning |
598
+ | --- | --- |
599
+ | `foreign-block-name` | a renderer keyed by a block another module owns |
600
+ | `undeclared-block` | a renderer for a block the manifest does not declare, or not for that surface's context |
601
+ | `storefront-import` | the storefront layer imports outside its allowed set |
602
+ | `raw-html` | `dangerouslySetInnerHTML` whose value is not `sanitizeRichHtml(…)` |
603
+ | `email-layer-import` | the e-mail layer imports React, a Node built-in or anything outside the e-mail renderer |
604
+ | `unscoped-stylesheet` | `./blocks.css` has a selector outside the module's prefix, or pulls in another stylesheet |
605
+ | `layer-without-subpath` | a layer's sources exist and the `exports` map does not publish them |
606
+
607
+ ### Keep old content rendering
150
608
 
151
- A renderer omitted from the bundle does not break the admin: the
152
- `PageBuilderEditor` merges the descriptor with the local config and
153
- substitutes a `MissingComponentPlaceholder` for any component the
154
- descriptor names but the bundle does not export. The placeholder renders
155
- nothing on the storefront unless the page is loaded with the
156
- `?cms_admin=1` query parameter (preview mode).
609
+ A block's name is permanent, and its stored props outlive the version of the
610
+ module that wrote them. A renderer must draw every shape of props the module
611
+ ever published: ignore a prop it does not know, and fall back to a default for
612
+ one that is missing. A change that cannot be made that way is a new block
613
+ under a new name, with the old renderer kept.
157
614
 
158
615
  ## Component name namespacing
159
616
 
@@ -183,10 +640,10 @@ name at least one surface:
183
640
  contexts: ['cms'], // CMS-only
184
641
  ```
185
642
 
186
- In `@endora-commerce/cms-components`, wrap the Puck config with
187
- `definePageBuilderComponent` from `@endora-commerce/page-builder-core` so the admin
188
- palette filter stays in sync. Components without `email` / `invoice` in
189
- `contexts` never appear in those editors (e.g. a product carousel).
643
+ A block without `email` / `invoice` in `contexts` never appears in those
644
+ editors (e.g. a product carousel). A module ships renderers for the `cms` and
645
+ `email` contexts; `newsletter` shows the `email` blocks, and invoice blocks are
646
+ drawn by the invoices module.
190
647
 
191
648
  ## Responsive props and visibility (CMS only)
192
649
 
@@ -254,7 +711,7 @@ Use `createSpacingField`, `createBorderField`, and `createColorField` from
254
711
 
255
712
  | Priority | Idea | Why |
256
713
  | -------- | ---- | --- |
257
- | Medium | Newsletter ↔ module 048 | Auto-wire channel subscribe endpoint |
714
+ | Medium | Newsletter signup ↔ the `newsletter` module | Auto-wire channel subscribe endpoint |
258
715
  | Low | Contact ↔ forms module | Pick an existing form instead of iframe URL |
259
716
 
260
717
  `Accordion` / `Tabs` already cover FAQ-style sections; prefer those before a
@@ -262,7 +719,7 @@ dedicated FAQ component.
262
719
 
263
720
  ## Testing
264
721
 
265
- The platform ships a TDD scaffold for the SPI in
266
- `backend/test/integration/cms/page-builder-extension.test.ts`. Use the
267
- fixture in `backend/test/fixtures/cms/test-extension-module.ts` as a
268
- template when adding tests for your own contributions.
722
+ Use `backend/acceptance/block-renderers-fixture/` as the template for a package
723
+ that ships renderers, and `endora check` as its first test.
724
+ `backend/test/integration/cms/page-builder-extension.test.ts` covers the
725
+ declaration half: a manifest's blocks reaching the descriptor.
package/docs/cms/index.md CHANGED
@@ -216,11 +216,10 @@ mirrors; the asset-ref scan covers `body` for backward compatibility.
216
216
 
217
217
  ## Extending the Page Builder
218
218
 
219
- Other backend modules contribute components via the SPI in
220
- `packages/modules/cms/src/backend/services/page-builder-registry.ts`. See the
221
- [Extending the Page Builder](./extending-page-builder) guide for the
222
- end-to-end workflow: descriptor declaration, renderer shipping, and
223
- composition wiring.
219
+ Other modules declare their blocks in their own manifest and ship the renderers
220
+ in their own package. See the
221
+ [Extending the Page Builder](./extending-page-builder) guide: the manifest
222
+ declaration, the three renderer layers and the block stylesheet.
224
223
 
225
224
  ## Error codes
226
225
 
package/i18n/en.json CHANGED
@@ -39,6 +39,7 @@
39
39
  "status.draft": "Draft",
40
40
  "status.published": "Published",
41
41
  "pageBuilder.extensions": "Extensions",
42
+ "pageBuilder.blockPreview.unavailable": "This block has no preview in the editor. Its fields can be edited in the side panel.",
42
43
  "pageBuilder.loadingConfig": "Loading Page Builder config...",
43
44
  "pageBuilder.drawer.searchPlaceholder": "Search components…",
44
45
  "pageBuilder.drawer.searchEmpty": "No components match your search.",