@core / blocks

1.0.0 ▾

1.0.0

verifiedMIT

GitHub

Page builder blocks: 15 accessible sections (hero, pricing, FAQ with JSON-LD…), admin editor and registry for more

Code25 filesContext~681 tokensscan passed

~681 tokens→ src/lib/blocks/AGENTS.md→ .cursor/rules/genpm-core-blocks.mdc

This is exactly what your AI reads when it works in src/lib/blocks. Nothing else is added to its context.

@core/blocks — rules for AI agents

Purpose

Page sections that editors combine from the admin: hero, features, benefits, testimonials, logos, pricing, FAQ (with FAQPage JSON-LD), call to action, gallery, video, stats, comparison, guarantee, rich text and form. Each block is a zod schema + editor fields + a React component. Other packages and kits add their own blocks (product grid, latest posts…) to the same registry. Blocks are stored as JSON inside @core/content entries; no tables of its own.

Map

index.ts — defineBlock, createBlockRegistry, coreBlocks (and each block), RenderBlocks, collectMediaIds.
core/*.ts — one file per block. parts.ts — Section, Heading, Img, CtaLink, JsonLd for new blocks.
media.ts — loadBlockMedia(blocks, registry) (server: one query to @core/media).
editor.ts — 'use client': blocksRenderer(blockMeta(registry)) for AdminApp. blocks.css — styles on @core/ui tokens.

Integration

Create src/genpm/blocks.ts: export const blocks = createBlockRegistry([...coreBlocks /*, kit blocks */]);
Add a field to a content collection: schema blocks: blocks.schema, admin field blocks.field('blocks', 'Sections').
Admin: compute blockMeta(blocks) on the server and pass it to the client component that renders <AdminApp renderers={{ blocks: blocksRenderer(meta), /* richText, media… */ }} /> (never import the registry in client code).

Page (server component):

const media = await loadBlockMedia(page.data.blocks, blocks);
return <RenderBlocks blocks={page.data.blocks} registry={blocks} media={media}
  renderForm={(key) => <Form formKey={key} />} embeds={hasConsent('marketing') ? 'iframe' : 'link'} />;

Styles: import src/lib/ui/ui.css then src/lib/blocks/blocks.css in the root layout.
Verify: a page with every block passes axe and has one h1; a block with an unknown type renders nothing and warns in dev.

Conventions

A new block = new file with defineBlock + entry in the registry. Never add if (type === …) to RenderBlocks.
Use Section and Heading with ctx.level (items one level below); only blocks with pageTitle may become the h1.
Images are media ids resolved with loadBlockMedia; links go through the href schema (no javascript:).
Text in blocks is plain text; use the rich-text block for formatting.

Don't

Don't render user HTML (dangerouslySetInnerHTML) except via JsonLd, which escapes <, > and &.
Don't load video iframes without marketing consent (embeds: 'link' is the default).
Don't invent testimonials, ratings or statistics; the editor help texts remind users these must be real and verifiable.

# @core/blocks — rules for AI agents

## Purpose
Page sections that editors combine from the admin: hero, features, benefits, testimonials, logos, pricing, FAQ (with
FAQPage JSON-LD), call to action, gallery, video, stats, comparison, guarantee, rich text and form. Each block is a
zod schema + editor fields + a React component. Other packages and kits add their own blocks (product grid, latest
posts…) to the same registry. Blocks are stored as JSON inside @core/content entries; no tables of its own.

## Map
- `index.ts` — `defineBlock`, `createBlockRegistry`, `coreBlocks` (and each block), `RenderBlocks`, `collectMediaIds`.
- `core/*.ts` — one file per block. `parts.ts` — `Section`, `Heading`, `Img`, `CtaLink`, `JsonLd` for new blocks.
- `media.ts` — `loadBlockMedia(blocks, registry)` (server: one query to @core/media).
- `editor.ts` — `'use client'`: `blocksRenderer(blockMeta(registry))` for `AdminApp`. `blocks.css` — styles on @core/ui tokens.

## Integration
1. Create `src/genpm/blocks.ts`: `export const blocks = createBlockRegistry([...coreBlocks /*, kit blocks */]);`
2. Add a field to a content collection: schema `blocks: blocks.schema`, admin field `blocks.field('blocks', 'Sections')`.
3. Admin: compute `blockMeta(blocks)` on the server and pass it to the client component that renders
   `<AdminApp renderers={{ blocks: blocksRenderer(meta), /* richText, media… */ }} />` (never import the registry in client code).
4. Page (server component):
   ```tsx
   const media = await loadBlockMedia(page.data.blocks, blocks);
   return <RenderBlocks blocks={page.data.blocks} registry={blocks} media={media}
     renderForm={(key) => <Form formKey={key} />} embeds={hasConsent('marketing') ? 'iframe' : 'link'} />;
   ```
5. Styles: import `src/lib/ui/ui.css` then `src/lib/blocks/blocks.css` in the root layout.
6. Verify: a page with every block passes axe and has one `h1`; a block with an unknown type renders nothing and warns in dev.

## Conventions
- A new block = new file with `defineBlock` + entry in the registry. Never add `if (type === …)` to `RenderBlocks`.
- Use `Section` and `Heading` with `ctx.level` (items one level below); only blocks with `pageTitle` may become the `h1`.
- Images are media ids resolved with `loadBlockMedia`; links go through the `href` schema (no `javascript:`).
- Text in blocks is plain text; use the `rich-text` block for formatting.

## Don't
- Don't render user HTML (`dangerouslySetInnerHTML`) except via `JsonLd`, which escapes `<`, `>` and `&`.
- Don't load video iframes without marketing consent (`embeds: 'link'` is the default).
- Don't invent testimonials, ratings or statistics; the editor help texts remind users these must be real and verifiable.

The exact tree that will be injected, after .genpmignore. Pinned to

src/lib/blocks/LICENSEread-only · a255d6d

MIT License

Copyright (c) 2026 GenPM

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.