Documentation / blocks-core

Blocks Core

Foundation
@wabbit/tome-blocks-corev0.18.0

Core primitives for the Tome block system — the block/bundle registry, defineBlock/defineBundle factories, variant-aware admin components (BlockPicker, VariantPicker), and the thumbnail pipeline; upstream dependency for every tome-blocks-* pack.

Installnpm install @wabbit/tome-blocks-core

Overview

@wabbit/tome-blocks-core

Core primitives for the Tome block system. Provides the registry, type definitions, defineBlock / defineBundle factories, admin components (BlockPicker, VariantPicker), and the thumbnail pipeline (SVG wireframes, plus an opt-in raster screenshot source).

This package is the upstream dependency for all @wabbit/tome-blocks-* bundle packages and the @wabbit/tome-blocks meta-package.

Add Tome blocks to an existing Payload project

The canonical path for adding one or more @wabbit/tome-blocks-* packs to a Payload project that already exists — the Payload website template, a hand-rolled site, anything with its own payload.config.ts and its own blocks field. Every pack README's own "Install into an existing Payload project" section points back here for the parts that don't change per pack.

1. Registry access (once per machine)

Add the scope mapping to your project's .npmrc (skip if it's already there):

@wabbit:registry=https://npm.wabbit.com/

Every install then needs an install token — the registry answers no anonymous reads, free packs and the shared foundation packages included. Getting one costs nothing:

  1. Create a free account at wabbit.com/signup (no card).
  2. In Account → Credentials, claim the free license and generate an install token. It's shown exactly once; if you lose it, generate a new one.
  3. Put it in your user-level ~/.npmrc (never the project one, so it stays out of your repository):
//npm.wabbit.com/:_authToken=<your token>

A free token installs the free packs (@wabbit/tome-blocks-marketing-starter, @wabbit/tome-blocks-content-writer) and everything they depend on (blocks-core, blocks-extras, blocks-house, tome-ui). Paid packs install with the same token once your account holds the plan or pack — see wabbit.com/subscribe. The step-by-step customer guide is wabbit.com/docs/get-started.

2. Install a pack

npm install @wabbit/tome-blocks-marketing-starter

Every pack declares @wabbit/tome-blocks-core (and, where it uses them, @wabbit/tome-blocks-house/@wabbit/tome-blocks-extras) as a required peer, and this package in turn declares @wabbit/tome-ui as a required peer. npm 7+ and pnpm install required peers automatically, so this one command is the whole install — there's no separate npm install @wabbit/tome-blocks-core @wabbit/tome-ui step.

3. Load the design tokens

One line in your site's global CSS:

@import '@wabbit/tome-blocks-core/styles.css';

It imports the @wabbit/tome-ui token layer. Block CSS reads --tome-* custom properties, almost always with no fallback — skip this line and blocks render as bare, unstyled HTML.

4. Add blocks to a blocks field

Every pack exports its blocks as descriptors — a meta plus a .block(config?) factory that returns a Payload Block. Import the ones you want and add them alongside whatever your field already has:

// payload.config.ts
import { ctaBlock, faqBlock } from '@wabbit/tome-blocks-marketing-starter'

// inside the `pages` collection's `layout` field:
{
  name: 'layout',
  type: 'blocks',
  blocks: [
    ...existingBlocks,
    ctaBlock.block(),
    faqBlock.block(),
  ],
}

5. Render them

Two prop shapes exist, and mixing them up is a runtime crash. Every pack renderer is typed React.FC<BlockRenderProps<T>> — it destructures { block, className, index }, with a block's own fields nested under block. That is the opposite of how most Payload sites render a blocks field.

The grid is required here, not optional. Every pack block places its own inner sections on @wabbit/tome-ui's named grid lines (content-start/content-end, full-start/full-end, etc.) via CSS grid-template-columns: subgrid. Skip it and nothing errors or warns at install or build time — the page just renders with every block flush against the viewport edge, zero gutters (verified live against this exact recipe, 2026-09-24 — see scripts/blocks-fresh-install-smoke.mjs in tome-core for the reproduction and the fix, proven fail-then-pass). The fix is this package's own RenderBlocks, which already wraps each block in the [data-tome-block-wrapper] subgrid div those named lines need — use it instead of a hand-rolled .map() loop, and put the grid class on its container via gridClassName:

// blockComponents.ts
import { renderers as marketingRenderers } from '@wabbit/tome-blocks-marketing-starter/render/register'
import { adaptRenderersForPayload } from '@wabbit/tome-blocks-core/render'

export const blockComponents = {
  ...adaptRenderersForPayload(marketingRenderers),
  // your own site-native components, already spread-props shaped, pass through as-is
}
// src/blocks/RenderBlocks.tsx — delegate to this package's RenderBlocks
// rather than a hand-rolled array loop, and don't pass `defaultColumnSpan`:
// leaving every wrapper at its default `1 / -1` keeps the FULL set of named
// lines (including `full-start`/`full-end`) available inside each block's
// own subgrid — pre-clipping the wrapper to content columns silently drops
// the lines outside that range from every block's subgrid.
import { blockComponents } from './blockComponents'
import { RenderBlocks as TomeRenderBlocks } from '@wabbit/tome-blocks-core/render'
import gridStyles from '@wabbit/tome-ui/grid'

export function RenderBlocks({ blocks }: { blocks: LayoutBlock[] }) {
  return <TomeRenderBlocks blocks={blocks} components={blockComponents} gridClassName={gridStyles.grid} />
}

Blocks that declare meta.pinnedBand: true (e.g. media-panel, pull-interlude in @wabbit/tome-blocks-cinema-pack) always span 1 / -1 at their own render root — no site-level handling needed, it's baked into each such block's own CSS and beats this package's :where(.grid [data-tome-block-wrapper] > *) { grid-column: 2 / -2 } default on ordinary specificity.

If you're dispatching one block at a time and want it nested (no spreading), use RenderBlock — it calls the pack renderer exactly the shape it expects, no adapting needed. It needs the same grid ancestor as above for any block reading named lines:

import { RenderBlock } from '@wabbit/tome-blocks-core'
import { renderers } from '@wabbit/tome-blocks-marketing-starter/render/register'

<RenderBlock block={block} components={renderers} />

That's the whole path: registry access, install, CSS import, add blocks to a field, render (through this package's RenderBlocks with the grid — not optional, see step 5). Everything below is optional.

6. Optional — override the defaults

  • Rich text and images render with no adapter setup. This package ships a default rich-text adapter (built on @payloadcms/richtext-lexical/react, already a required peer) and a default media adapter (resolves a Payload upload document or id to a plain <img>) — nothing to register for either to work. Upload fields must be populated at depth >= 1; a bare, unpopulated id can't be resolved without a fetch and renders nothing, with a one-time console warning in every environment (not just dev). Call registerBlockAdapters() only to override a default — swap in next/image, a route-transition-aware link, etc.:
  // lib/blockAdapters.ts — import from BOTH payload.config.ts AND your root layout
  import { registerBlockAdapters } from '@wabbit/tome-blocks-core/adapters'

  registerBlockAdapters({
    richText: { RichText: MyRichText, isRichTextActive: true },
    media: { Media: MyImageComponent, isMediaActive: true },
    link: { Link: MyTransitionLink, isLinkActive: true },
  })
  • Coming from the Payload website template. Verified live against create-payload-app -t website (2026-09-24) — the exact spots that bite:
  • Slug collisions. cta/banner (@wabbit/tome-blocks-marketing-starter), archive (@wabbit/tome-blocks-content-writer), and content/code (@wabbit/tome-blocks-extras) share a slug with a block the stock website/ecommerce templates already register in the same field (docs/blocks-slug-collisions.md has the full audit). Rename just the colliding ones at the point you assemble your blocks array and your renderer map — a pack's own default slug never changes, so no stored data migrates:
    import { applyBlockSlugOverrides, remapRendererSlugs } from '@wabbit/tome-blocks-core/slugOverrides'

    const overrides = { cta: 'tomeCta' }
    const blocks = applyBlockSlugOverrides([...existingBlocks, ctaBlock.block()], overrides)
    const components = {
      ...blockComponents,
      ...remapRendererSlugs(adaptRenderersForPayload(marketingRenderers), overrides),
    }
  • Global CSS lives at `src/app/(frontend)/globals.css` — inside the (frontend) route-group parens, easy to miss. Put the step-3 @import right after the template's own @import 'tw-animate-css' line, before @config.
  • `src/blocks/RenderBlocks.tsx`'s `blockComponents` needs a type annotation. The template declares it with no type, so TypeScript infers a closed literal type from its 5 built-in blocks; spreading a pack's Record<string, Component> renderer map into it fails with TS7053 at the blockComponents[blockType] lookup — which, as a side effect, also turns the template's own pre-existing {/* @ts-expect-error ... */} above <Block {...block} /> into a second error (TS2578, "unused directive"), since the widened lookup no longer produces the mismatch that comment was suppressing. Fix both together: annotate blockComponents: Partial<Record<string, React.ComponentType<any>>> (matches this package's own RenderBlocksProps['components'] type) and delete that @ts-expect-error comment.
  • Re-run `payload generate:types` after adding Tome blocks to a collection's blocks field, before your next build — otherwise the build's own TypeScript pass sees a stale generated union missing the new slugs.
  • The render step above (step 5) applies here too — swap the template's hand-rolled .map() loop in RenderBlocks.tsx for this package's own RenderBlocks with gridClassName, exactly as shown there. Skipping it is the single most common way this template ends up with ungapped Tome blocks.
  • Site-wide element reset. @wabbit/tome-ui/base resets body/h1–h6/p/ul/ol and similar elements off tokens. It is deliberately NOT part of the required CSS import in step 3 — it applies a site-wide reset that can override a consumer's own typography/reset choices well outside the blocks themselves. Import it only if you want that reset:
  @import '@wabbit/tome-ui/base';

Public API

| Export | Description | |--------|-------------| | defineBlock(meta, factory, variants?) | Register a block descriptor and auto-inject _variant field when variants are declared | | defineBundle(meta, blocks) | Register a bundle descriptor | | buildVariantField(variants) | Build the hidden _variant select field | | createVariantAwareBlock({ factory, variants }) | Wrap a factory to apply variant fieldOverrides per-config (also exported, with hasVariants and VariantAwareBlockInput, from the ./variants subpath) | | hasVariants(descriptor) | Type guard: does a descriptor declare variants? | | blockRegistry | Global BlockRegistry singleton (the registry classes and both singletons are also exported from the ./registry subpath) | | bundleRegistry | Global BundleRegistry singleton | | BlockRegistry | Class — block CRUD, variant lookup, resolve() | | BundleRegistry | Class — bundle CRUD, resolve(), resolveMany() | | RESERVED_VARIANT_FIELD | '_variant' — reserved field name constant | | BLOCK_CATEGORIES (also ./categories) | Category constant map — the eight canonical display values (Content, Layout, Actions, Data, Navigation, Social, Marketing, Utility); the standalone subpath is Payload- and React-free | | BlockPicker | Payload admin component replacing the block drawer | | VariantPicker | Payload admin component for the _variant select field | | useTheme() | Hook: observes document.documentElement[data-theme] | | Thumbnail | React component rendering a block variant's thumbnail — raster screenshot when a ThumbnailSourceProvider resolves one, else the inline SVG wireframe | | sanitizeSvg(svg) | Strip XSS vectors from SVG strings | | resolveThumbnail(blockSlug, variantSlug?) | Resolve SVG string from the generated index | | PLACEHOLDER_SVG | Wireframe placeholder SVG used for missing thumbnails | | ThumbnailSourceProvider | Context provider for raster thumbnails — takes a resolver: (blockSlug, variantSlug) => { light?, dark? } \| undefined | | useThumbnailSource() | Hook consumed internally by Thumbnail; returns { resolver, theme } | | useGalleryThumbsManifest(manifestUrl?) | Hook: fetches a thumbs-manifest.json-shaped file client-side and returns a resolver (or undefined on 404/error) | | GalleryThumbsProvider | One-liner combining useGalleryThumbsManifest + ThumbnailSourceProvider — what BlockPicker wires internally | | flattenThumbsManifest(manifest) | Flatten a bundle-keyed manifest into a blockSlug-keyed index (first-wins on slug collision, dev-console warn) | | buildResolverFromFlatIndex(flat) | Build a ThumbnailResolver from an already-flattened index | | registerRenderer(slug, component) | Register a block render component | | getRenderer(slug) | Look up a block renderer | | hasRenderer(slug) | Check whether a renderer is registered for a block slug | | getAllRenderers() | Return the full slug → renderer registry map | | RenderBlock | React component: renders a single block by blockType | | RenderBlocks | React component: renders an array of blocks | | BLOCK_CATALOG | Static AI-readable block catalog array | | columnSpan (./fields/columnSpan) | Optional grid-column override Field for top-level blocks rendered through RenderBlocks | | registerBlockBundleProductType({ productTypeRegistry, registerProductTypeHooks }) (./registry/productHooks) | Registers the block-bundle product type in @wabbit/tome-catalog's productTypeRegistry and its getCardFields hook through @wabbit/tome-core's registerProductTypeHooks. You pass both in: blocks-core depends on neither package, so nothing is discovered for you. Importing the subpath also attempts the registration through require(), which does nothing under native-Node ESM (for example payload generate:types); call this explicitly from payload.config.ts whenever you compose blocks with catalog. Idempotent | | buildUsageManifest(descriptors) (./usage) | Flattens block descriptors' authored usage metadata into a machine-readable manifest for agent block selection/sequencing | | useDebouncedResize(...) (./utilities/useDebouncedResize) | Shared resize-debounce hook — single timer collapses resize/orientationchange into one callback | | formatDisplayDate(...) (./utilities/formatDisplayDate) | Shared display-date formatter — fixed locale + UTC by default for hydration-safe server/client parity | | useDocumentTheme(defaultTheme?) (./utilities/useDocumentTheme) | Low-level hook observing document.documentElement[data-theme] via MutationObserver; SSR-safe |

Types

All of the below are re-exported from the root barrel and are also importable from the standalone ./types entry point (types plus the reserved field-name constants RESERVED_VARIANT_FIELD, RESERVED_COLSPAN_FIELD, RESERVED_ROWSPAN_FIELD, RESERVED_ORDER_FIELD — no registry, no React).

BlockMeta, BlockDescriptor, BundleMeta, BundleDescriptor, BlockCategory, BlockVariant, EditorialHint, ThumbnailIndex, BlockRenderProps, BlockRenderer, BlockPickerProps, VariantPickerProps, ThumbnailProps, VariantAwareBlockInput, BlockCatalogEntry, ThumbnailResolver, ThumbnailRasterPaths, RasterThumbsManifest, ThumbnailSourceProviderProps, GalleryThumbsProviderProps

Install (register every block from scratch)

This is the "build a fresh Payload config from nothing" path — register the whole registry and resolve every known block into one field. For adding Tome blocks to a project that already has its own blocks field and its own blocks, see "Add Tome blocks to an existing Payload project" above instead.

pnpm add @wabbit/tome-blocks-core @wabbit/tome-ui payload @payloadcms/richtext-lexical react react-dom

Required peers: payload >=3.67.0, @payloadcms/richtext-lexical >=3.67.0, react >=19.0.0, react-dom >=19.0.0, @wabbit/tome-ui >=0.13.0 <1.0.0. Optional peer: @payloadcms/ui >=3.67.0 (only the admin BlockPicker/VariantPicker surface needs it — the render/adapter half needs only React). @wabbit/tome-core and @wabbit/tome-catalog are no longer peers of this package at all (2026-09-24) — registerBlockBundleProductType() now takes both registries as explicit dependency-injected arguments instead of discovering them via an optional peer, which kept better-auth's own peer graph out of a plain Payload site's install.

Wire in your payload.config.ts:

import { blockRegistry, bundleRegistry } from '@wabbit/tome-blocks-core'
// Import your bundle package
import { register } from '@wabbit/tome-blocks-marketing-starter'

register(blockRegistry, bundleRegistry)

export default buildConfig({
  collections: [
    {
      slug: 'pages',
      fields: [
        {
          name: 'layout',
          type: 'blocks',
          blocks: blockRegistry.resolveAll(),
          admin: {
            components: {
              Field: BlockPicker,
            },
          },
        },
      ],
    },
  ],
})

Peer dependencies

Generated from package.json#peerDependencies (the README gate fails if this table and the manifest disagree).

| Peer | Range | Required | |---|---|---| | @payloadcms/richtext-lexical | >=3.67.0 | yes | | @payloadcms/ui | >=3.67.0 | no (optional) | | payload | >=3.67.0 | yes | | react | >=19.0.0 | yes | | react-dom | >=19.0.0 | yes | | @wabbit/tome-ui | >=0.13.0 <1.0.0 | yes |

Only @payloadcms/ui is optional: this package is two surfaces in one, and the render/adapter half needs only React + @wabbit/tome-ui tokens, while the admin half (BlockPicker, VariantPicker, thumbnails) needs @payloadcms/ui. @wabbit/tome-catalog and @wabbit/tome-core are not peers of this package (removed 2026-09-24, standalone-install readiness W1) — declaring even an optional peer on @wabbit/tome-core dragged its own optional better-auth → @sveltejs/kit → vite@8 peer graph into a plain Payload site's install and produced an ERESOLVE against the site's own vite@7. The block-bundle product-type registration (./registry/productHooks) now takes both registries as explicit, dependency-injected arguments instead. fuse.js is a real dependency (the picker's fuzzy search).

Thumbnail pipeline

# Regenerate from blocks tree (default: packages/blocks/src/blocks)
pnpm thumbnails:index

# Validate all committed SVGs
pnpm thumbnails:check

# scan specific bundle package roots
pnpm thumbnails:index --roots packages/blocks-marketing-starter,packages/blocks-content-writer

Raster thumbnails (opt-in)

BlockPicker fetches /gallery-thumbs/thumbs-manifest.json client-side by default and, when a site has run the gallery's build-time screenshot capture CLI, every <Thumbnail> in the picker renders the real screenshot instead of the SVG wireframe. No wiring required beyond the manifest existing at that path — a 404 is a silent no-op and the picker falls back to the SVG pipeline unchanged:

// No config needed if the manifest lives at the default path:
<Field: BlockPicker />

// Custom manifest path:
<BlockPicker onSelect={...} thumbsManifestUrl="/my-thumbs/manifest.json" />

// Opt out of the fetch entirely:
<BlockPicker onSelect={...} thumbsManifestUrl={null} />

For a custom Field wrapper (rather than Field: BlockPicker as-is), or to give raster thumbnails to a <Thumbnail> rendered outside BlockPicker, use the primitives directly:

import { GalleryThumbsProvider, Thumbnail } from '@wabbit/tome-blocks-core'

<GalleryThumbsProvider manifestUrl="/gallery-thumbs/thumbs-manifest.json">
  <Thumbnail blockSlug="cta" variantSlug="minimal" />
</GalleryThumbsProvider>

Theme (light/dark) is picked up from document.documentElement[data-theme] — the same mechanism useTheme() uses for the rest of the admin UI — observed once per provider, not once per thumbnail.

Server / client posture

This package's .tsx surface splits cleanly along its own subpath boundaries (verified by grep 2026-07-12):

  • `./render` — RenderBlock/RenderBlocks (the actual per-block render dispatch primitives) carry no 'use client' directive. Safe to import from a Server Component; the client boundary, if any, lives in whatever block renderer they dispatch to, not in these primitives themselves.
  • `./admin` — the entire BlockPicker family (BlockPicker, BlockCard, BundleFilter, CategorySection, EmptyState, RecentFavorites, SearchInput, TagFilter) and the VariantPicker family (VariantPicker, VariantPickerField) are all 'use client' — genuine interactive Payload admin-UI surfaces (search, filtering, hover state). These belong in the Payload admin bundle only, never a site's public render path.
  • `./thumbnails` — Thumbnail and ThumbnailSource are 'use client' (theme observation via useTheme(), raster/SVG fallback logic).
  • `./adapters` — resolveRichText.tsx is server-safe (no directive); its two context-consuming siblings, context.tsx (MediaAdapterContext/RichTextAdapterContext and their MediaAdapterProvider/RichTextAdapterProvider) and MediaContextFallback.tsx/RichTextContextFallback.tsx, are 'use client' because they wrap useContext.

Net: import ./render from server code, ./admin and ./thumbnails only from the Payload admin panel's client bundle.

Decisions that shaped this package

  • Adapters are a module-scope `globalThis` registry, not Context-only — 108 of 109 block renderers across the packs were forced client-only because the old useRichTextAdapter/useMediaAdapter contract could only be read via Context hooks defined in 'use client' modules, even though adapter config is site-wide, not per-request. registerBlockAdapters() plus the environment-agnostic resolveRichText/resolveMedia functions let static renderers drop 'use client' and become RSCs.
  • The client Context survives as the override/interop layer, not the primary path — where a provider is mounted (Payload admin live-preview, interactive blocks), it wins over the module registry, so existing provider-based sites see zero behavior change during migration.
  • `RenderBlock` was rewritten server-safe rather than deleted — kept for consumers needing per-item dispatch (parity with RenderBlocks' components prop as a registry-free escape hatch), on the condition that it ships only after registerAllRenderers() gives the server graph a real registration path — a bare RSC RenderBlock reading the registry before that would silently resolve nothing.
  • Motion-consuming blocks stay client by design — the adapter contract deliberately does not touch useMotionAdapters; motion is intrinsically client (GSAP/refs/effects), so the pattern is a small 'use client' leaf around a server-rendered static shell, not a server-safe motion adapter.

Exports

  • @wabbit/tome-blocks-core
  • @wabbit/tome-blocks-core/styles.css
  • @wabbit/tome-blocks-core/types
  • @wabbit/tome-blocks-core/categories
  • @wabbit/tome-blocks-core/slugOverrides
  • @wabbit/tome-blocks-core/defineBlock
  • @wabbit/tome-blocks-core/defineBundle
  • @wabbit/tome-blocks-core/fields/columnSpan
  • @wabbit/tome-blocks-core/registry
  • @wabbit/tome-blocks-core/registry/productHooks
  • @wabbit/tome-blocks-core/variants
  • @wabbit/tome-blocks-core/usage
  • @wabbit/tome-blocks-core/render
  • @wabbit/tome-blocks-core/adapters
  • @wabbit/tome-blocks-core/thumbnails
  • @wabbit/tome-blocks-core/admin
  • @wabbit/tome-blocks-core/utilities/useDocumentTheme
  • @wabbit/tome-blocks-core/utilities/useDebouncedResize
  • @wabbit/tome-blocks-core/utilities/formatDisplayDate

Changelog

v0.18.0minor

c3468b0: New server-safe pack helpers, so block packs stop copying the same boilerplate (2026-09-24 audit A3 #8). `createPackRegistrar(blocks, bundle)` builds a pack's idempotent `register(blockRegistry, bundleRegistry)` entry point; `createLayerProbe(layerName, load)` is the memoized "is this Tome layer registered?" check for domain packs (the pack keeps the dynamic `import('@wabbit/tome-core/…')` literal, so blocks-core still has no core dependency); both ship from `./registry` and the root. `mediaRelation(config)` returns the `relationTo` for a media field (`config.mediaCollection ?? 'media'`, typed as `CollectionSlug`); it ships from `./defineBlock` and the root. No new subpaths.

  • c3468b0: New server-safe pack helpers, so block packs stop copying the same boilerplate (2026-09-24 audit A3 #8). `createPackRegistrar(blocks, bundle)` builds a pack's idempotent `register(blockRegistry, bundleRegistry)` entry point; `createLayerProbe(layerName, load)` is the memoized "is this Tome layer registered?" check for domain packs (the pack keeps the dynamic `import('@wabbit/tome-core/…')` literal, so blocks-core still has no core dependency); both ship from `./registry` and the root. `mediaRelation(config)` returns the `relationTo` for a media field (`config.mediaCollection ?? 'media'`, typed as `CollectionSlug`); it ships from `./defineBlock` and the root. No new subpaths.
v0.17.1patch

15006ce: README: correct the registry-access step. It said free-tier packs install anonymously; the registry now requires an install token for every read (free packs and shared foundation packages included). The walkthrough now explains the free path — a no-card account at wabbit.com/signup, a token from Account → Credentials, placed in the user-level `~/.npmrc` — what a free token covers (the two free packs plus `blocks-core`, `blocks-extras`, `blocks-house`, `tome-ui`), and links the customer guide at wabbit.com/docs/get-started. Docs only; no code change.

  • 15006ce: README: correct the registry-access step. It said free-tier packs install anonymously; the registry now requires an install token for every read (free packs and shared foundation packages included). The walkthrough now explains the free path — a no-card account at wabbit.com/signup, a token from Account → Credentials, placed in the user-level `~/.npmrc` — what a free token covers (the two free packs plus `blocks-core`, `blocks-extras`, `blocks-house`, `tome-ui`), and links the customer guide at wabbit.com/docs/get-started. Docs only; no code change.
v0.17.0minor

404d325: Tome block packs now install into an existing Payload project the way the README says: one `npm install`, one CSS import, no undocumented steps. Proven by the new fresh-install smoke test (`scripts/blocks-fresh-install-smoke.mjs`) against a brand-new `create-payload-app` website-template site. **Consumers: list `@wabbit/tome-blocks-core` and `@wabbit/tome-ui` in your own `package.json`** if you import from them (npm 7+ and pnpm install required peers automatically, so a fresh `npm install` of a pack already brings them in). - **One shared `blocks-core` per site.** Every pack, `blocks-house` and `blocks-extras` now declare `@wabbit/tome-blocks-core` (and, where used, `-house` / `-extras`) as a required peer with an explicit range instead of a regular dependency, so a site gets exactly one hoisted copy and one adapter registry. - **No more ERESOLVE in plain Payload sites.** `blocks-core` no longer declares `@wabbit/tome-core` or `@wabbit/tome-catalog` (their optional peer graph pulled `better-auth` → `@sveltejs/kit` → `vite@8` against a site's `vite@7`). The `block-bundle` product type still auto-registers when both are installed; new structural types `BlockBundleProductTypeDeps`, `BlockBundleProductTypeRegistryLike`, `RegisterProductTypeHooksLike`. - **Tokens in one line:** `@import '@wabbit/tome-blocks-core/styles.css';` (new export; imports `@wabbit/tome-ui/tokens`). `@wabbit/tome-ui` is now a required peer of `blocks-core`. - **Rich text and images render with no adapter setup.** Built-in defaults render Lexical through `@payloadcms/richtext-lexical/react` and resolve populated Payload uploads; an unpopulated upload id warns once in every environment (previously content vanished silently in production). Registered adapters still win. - **Payload's spread-props convention:** new `adaptRenderersForPayload(renderers)` / `adaptRendererForPayload(Component)` wrap any pack's `renderers` map for a site that renders `<Block {...block} />`. - **Slug collisions with Payload's templates** (`cta`, `banner`, `archive`, `content`, `code`): new `applyBlockSlugOverrides(blocks, overrides)` and `remapRendererSlugs(renderers, overrides)` (`@wabbit/tome-blocks-core/slugOverrides`). Defaults are unchanged; no stored data migrates. - **`blocks-house`** owns `gsap` and `hls.js` as dependencies (previously optional peers that still broke the build when missing), and registers GSAP's `ScrollTrigger` itself before first use. - **Full-bleed bands actually span the grid.** Eight `pinnedBand` blocks (cinema-pack AmbientBand, MediaPanel, PullInterlude, SceneCaption, ScenePlate, ScrubStory, StatementBand; blocks-house FullBleedInterstitial) now declare `grid-column: 1 / -1` at their root as the contract requires. **Visible change:** inside a tome-ui `.grid`, these render edge to edge where they were previously squeezed to content width. - **`@wabbit/tome-ui`:** `.grid` declares `reading-start` / `reading-end` below 768px (aliased to the content column), so blocks placed on the reading column no longer collapse to a sliver on phones. - Every pack README gains an "Install into an existing Payload project" section and a peer table that matches `package.json`; `blocks-core`'s README carries the full walkthrough.

  • 404d325: Tome block packs now install into an existing Payload project the way the README says: one `npm install`, one CSS import, no undocumented steps. Proven by the new fresh-install smoke test (`scripts/blocks-fresh-install-smoke.mjs`) against a brand-new `create-payload-app` website-template site. **Consumers: list `@wabbit/tome-blocks-core` and `@wabbit/tome-ui` in your own `package.json`** if you import from them (npm 7+ and pnpm install required peers automatically, so a fresh `npm install` of a pack already brings them in). - **One shared `blocks-core` per site.** Every pack, `blocks-house` and `blocks-extras` now declare `@wabbit/tome-blocks-core` (and, where used, `-house` / `-extras`) as a required peer with an explicit range instead of a regular dependency, so a site gets exactly one hoisted copy and one adapter registry. - **No more ERESOLVE in plain Payload sites.** `blocks-core` no longer declares `@wabbit/tome-core` or `@wabbit/tome-catalog` (their optional peer graph pulled `better-auth` → `@sveltejs/kit` → `vite@8` against a site's `vite@7`). The `block-bundle` product type still auto-registers when both are installed; new structural types `BlockBundleProductTypeDeps`, `BlockBundleProductTypeRegistryLike`, `RegisterProductTypeHooksLike`. - **Tokens in one line:** `@import '@wabbit/tome-blocks-core/styles.css';` (new export; imports `@wabbit/tome-ui/tokens`). `@wabbit/tome-ui` is now a required peer of `blocks-core`. - **Rich text and images render with no adapter setup.** Built-in defaults render Lexical through `@payloadcms/richtext-lexical/react` and resolve populated Payload uploads; an unpopulated upload id warns once in every environment (previously content vanished silently in production). Registered adapters still win. - **Payload's spread-props convention:** new `adaptRenderersForPayload(renderers)` / `adaptRendererForPayload(Component)` wrap any pack's `renderers` map for a site that renders `<Block {...block} />`. - **Slug collisions with Payload's templates** (`cta`, `banner`, `archive`, `content`, `code`): new `applyBlockSlugOverrides(blocks, overrides)` and `remapRendererSlugs(renderers, overrides)` (`@wabbit/tome-blocks-core/slugOverrides`). Defaults are unchanged; no stored data migrates. - **`blocks-house`** owns `gsap` and `hls.js` as dependencies (previously optional peers that still broke the build when missing), and registers GSAP's `ScrollTrigger` itself before first use. - **Full-bleed bands actually span the grid.** Eight `pinnedBand` blocks (cinema-pack AmbientBand, MediaPanel, PullInterlude, SceneCaption, ScenePlate, ScrubStory, StatementBand; blocks-house FullBleedInterstitial) now declare `grid-column: 1 / -1` at their root as the contract requires. **Visible change:** inside a tome-ui `.grid`, these render edge to edge where they were previously squeezed to content width. - **`@wabbit/tome-ui`:** `.grid` declares `reading-start` / `reading-end` below 768px (aliased to the content column), so blocks placed on the reading column no longer collapse to a sliver on phones. - Every pack README gains an "Install into an existing Payload project" section and a peer table that matches `package.json`; `blocks-core`'s README carries the full walkthrough.
v0.16.6patch

e044594: `RenderBlock` accepts an optional `context` prop and forwards it to the renderer as `BlockRenderProps.context` (typed `unknown`; each pack narrows its own shape). Lets a host pass per-page data — e.g. a deal's live totals — to data-bound blocks without a React context provider. Omitting it changes nothing.

  • e044594: `RenderBlock` accepts an optional `context` prop and forwards it to the renderer as `BlockRenderProps.context` (typed `unknown`; each pack narrows its own shape). Lets a host pass per-page data — e.g. a deal's live totals — to data-bound blocks without a React context provider. Omitting it changes nothing.
v0.16.0minor

b01ca1f: Raise the `react` / `react-dom` peer floor to `>=19.0.0` across the linked blocks family. Every pack advertised `react: >=18.0.0` while `@wabbit/tome-core`, `chrome`, `forms`, `dispatch`, `longform` and `readout` all require `>=19` — so the React 18 support the packs claimed was **unreachable in any real Tome stack**: no consumer could satisfy both halves of the graph. The advertised range was not a supported configuration, it was a range nobody could install into. Ruled 2026-09-01: the floor becomes the truth. Their `devDependencies` said the same thing from the other direction: `react` and `@types/react` pinned to `^18.0.0` while the root `pnpm.overrides` has pinned `@types/react` to `19.2.14` for months, so every pack has in fact been developed and tested against React 19 types the whole time. Those pins move to `^19.0.0` — a manifest correction, not a version change; the resolved tree is byte-identical. One coordinated bump for the family (these eleven are `linked` in `.changeset/config.json`, so they version together by design). Consumer impact: a consumer genuinely on React 18 can no longer install these packs. That consumer could not have had a working Tome install anyway — the kernel would have refused the same graph. Anyone on React 19 sees no change.

  • b01ca1f: Raise the `react` / `react-dom` peer floor to `>=19.0.0` across the linked blocks family. Every pack advertised `react: >=18.0.0` while `@wabbit/tome-core`, `chrome`, `forms`, `dispatch`, `longform` and `readout` all require `>=19` — so the React 18 support the packs claimed was **unreachable in any real Tome stack**: no consumer could satisfy both halves of the graph. The advertised range was not a supported configuration, it was a range nobody could install into. Ruled 2026-09-01: the floor becomes the truth. Their `devDependencies` said the same thing from the other direction: `react` and `@types/react` pinned to `^18.0.0` while the root `pnpm.overrides` has pinned `@types/react` to `19.2.14` for months, so every pack has in fact been developed and tested against React 19 types the whole time. Those pins move to `^19.0.0` — a manifest correction, not a version change; the resolved tree is byte-identical. One coordinated bump for the family (these eleven are `linked` in `.changeset/config.json`, so they version together by design). Consumer impact: a consumer genuinely on React 18 can no longer install these packs. That consumer could not have had a working Tome install anyway — the kernel would have refused the same graph. Anyone on React 19 sees no change.
  • 57875ba: Block-adapter registry: each `registerBlockAdapters()` call is stamped with the React graph it was made from (`'server'` for the RSC graph, `'client'` for anything that can run hooks — browser and SSR), and the `*ContextFallback` components read the registry with `{ graph: currentAdapterGraph() }`, so a registration made from the other graph is treated as absent instead of rendered. On the server the RSC graph and the SSR graph share one `globalThis`; a component registered from the RSC graph holds client REFERENCES where it renders `'use client'` components, and rendering it inside the SSR pass calls that reference as a function ("Attempted to call the default export of … from the server"). Observed on wabbit.com/blocks/\_preview: a directive-free setup module registered the site's link component from the RSC graph, the preview harness rendered pack CTAs in a client tree with no `<LinkAdapterProvider>`, and every link-bearing block returned 500. Now that case renders the plain-anchor fallback and warns once in development, pointing at the provider. Ungated reads (`getLinkAdapter()` with no options) and server-graph reads are unchanged. New exports: `AdapterGraph`, `currentAdapterGraph`, and optional `{ graph }` on the register/get functions.
  • 0836ef5: dist now raw-Node loadable: relative specifiers get explicit extensions post-build. `build` gains `&& node ../../scripts/fix-dist-extensions.mjs --strict` as its last step, joining the 13 packages that already ran it. tsup builds `bundle: false` and emits relative specifiers exactly as the TypeScript source wrote them — extensionless — which bundlers resolve and raw Node does not (ESM `ERR_MODULE_NOT_FOUND`; CJS worse, `require('./x')` finds the ESM `.js` twin and Node 22+ `require(esm)` then dies on that file's own extensionless import). Every consumer outside a bundler hit this: the payload CLI under plain node, `generate:types`, `generate:importmap`, ops scripts, codegen tools. No source changes, no API changes, and bundler consumers are unaffected — extensioned relative specifiers are universally resolvable. Two supporting changes made the wiring possible, both in repo scripts rather than package source. `fix-dist-extensions.mjs` now skips bundler-asset specifiers (`.css`, `.module.css`, `.scss`, fonts, images, shaders) by explicit extension allowlist instead of reporting them as unresolvable — that single gap is why the 13 prior adopters were exactly the 13 packages that ship no CSS, since `--strict` exited 1 on any package with a relative stylesheet import. Dotted MODULE names (`./config.meta`, `./x.variants`, `./y.demo`) are deliberately NOT treated as assets and still get `.js`/`.cjs` appended. `assert-node-loadable.mjs` gained the matching carve-outs so the new repo-wide CI gate reports real defects only: a resolution failure whose path lands under `node_modules` is a peer SKIP (next@15 has no exports map, so `next/image` fails as an absolute path), and a bundler-asset load failure is an environmental SKIP (CJS surfaces it as `SyntaxError: Unexpected token '.'` raised from inside the stylesheet). Verified before/after on four packages built one at a time: print 8 FAIL → 0, readout 22 FAIL → 0, ai 3 FAIL → 0, gamification 2 FAIL → 0 (its failure was the other signature — a `directory import` missing `/index`). cop was already clean on a fresh build, so the audit's "27 of 46 fail" figure includes at least one package whose local dist was merely stale.
  • 73081e6: Manifest metadata: `homepage`, `bugs`, `engines`. All 46 publishable manifests were missing the three fields a consumer sees before any code (2026-09-01 sale-readiness audit §6). Metadata only — no source, no build, no runtime change. - `homepage` deep-links to that package README on GitHub (`.../tree/main/packages/<dir>#readme`). Without it a registry page links to the monorepo root and the reader has to guess which of 46 folders they want. - `bugs.url` points at the repo issue tracker, so a paying customer has a place to report a defect that is not email. - `engines.node` is `>=22`, matching the root `engines` and `.nvmrc` set the same day. This is a real floor, not decoration: CI on Node 20 could not expand the glob the block packs use for `node --test`, and a package installed on Node 20 fails at a runtime the installer cannot connect back to the version. The forcing function ships with the change: `scripts/assert-manifest-metadata.mjs` (root `pnpm assert:manifest-metadata`, wired into `platform-discipline.yml` beside `assert:license-metadata`) fails when any publishable manifest lacks `description`, `repository.directory` matching its own folder, `homepage`, `bugs`, `engines.node` equal to the repo floor, `license`, `files` or `sideEffects`. It reported 138 violations before this change and 0 after.
  • 090e984: README fixes surfaced by the extended `assert:readme-contract` gate (2026-09-01 sale-readiness audit, Tier 2), each verified against the package's own manifest or source: - **blocks-core** — the `./categories` and `./types` entry points are now named in the Public API section; both were published but undocumented. - **core** — added `/access/orgScoped`, `/access/vendorScoped`, `/infra/health` and `/infra/env-scaffold` to the additional-subpaths table, and noted that `/auth/collections/roles` has a real `/auth/collections/Roles` case alias in the exports map. - **crowdfund** — `CROWDFUND_LAYER_VERSION` is also published standalone at `./version`; the row now says so. - **dispatch** — the eight per-block `./blocks/*` config subpaths and all eight `./components/*` component subpaths are enumerated instead of one "etc." row. - **forms** — the peer table now lists `@wabbit/tome-core`, `@wabbit/tome-ui` and `typescript`, which are declared `peerDependencies` but appeared only in prose (or not at all). - **lms-ui** — `StudentProfileEditor` is flagged `@deprecated` in the component table, matching the tag its source already carries.
  • 73081e6: README peer tables, and the gate that now requires them. Sixteen packages declared `peerDependencies` and documented them nowhere a reader could scan — in prose inside an install paragraph, in a transposed "compatibility matrix" with the peers as columns, or not at all. Docs only; no source, no manifest, no runtime change (the one manifest change in this PR, admin's `sonner` peer, has its own changeset). Each of the sixteen gains a `## Peer dependencies` section generated from its own `package.json` — `| Peer | Range | Required |`, one row per peer, the range verbatim, `no (optional)` read from `peerDependenciesMeta`, plus one sentence on what is a real `dependency` rather than a peer and why the optional ones are optional. The worst omissions this surfaced: `@wabbit/tome-core` documented 2 of its 13 peers and left out both `next` and `@payloadcms/richtext-lexical`, which are required; `@wabbit/tome-admin` listed 5 of 20; `@wabbit/tome-readout` and `@wabbit/tome-sc` listed none. Eight block packs carried a hand-typed compatibility table that had drifted a full React major — still `>=18` after the peer floor moved to `>=19.0.0` — and none of the eight listed `react-dom` at all. Those tables are retired in favour of the generated one, with a line saying what they used to claim so the next reader does not reinstate them. The forcing function ships with the fix: `scripts/assert-readme-contract.mjs` now FAILS a package that declares peers without a peer table (a markdown table whose header row names a Peer and a Range column — the existing `Optional?` and `Notes` third columns still pass, so the thirty already-conforming READMEs were not touched). It is deliberately shape-only, not row-level: asserting that each row agrees with the manifest is the Tier 2 generation work. Verified non-vacuous by breaking one table's header and watching the gate fail, then restoring it. `CONTRIBUTING.md`'s assert-script list — which said "five" while sixteen existed — and the three guides that describe this gate were corrected in the same pass.
v0.15.24patch

1471078: Post Hero and Custom Hero catalog copy now describes what the blocks render, not their upstream military lore. Post Hero renders a full-bleed cover-image header with an accent-marked category tag, a visibility badge, and a mono byline strip — nothing about it reads "SITREP tactical," so the description, editorial role, and both variant descriptions now say what the reader sees. Custom Hero's description drops the "COP tactical layouts / SITREP post headers" jargon for plain treatment names. blocks-core BLOCK_CATALOG mirror entries updated to match. Enum IDs (`sitrep1`, `cop1`…) and schema field names are unchanged, per the 71d3b09 purge discipline.

  • 1471078: Post Hero and Custom Hero catalog copy now describes what the blocks render, not their upstream military lore. Post Hero renders a full-bleed cover-image header with an accent-marked category tag, a visibility badge, and a mono byline strip — nothing about it reads "SITREP tactical," so the description, editorial role, and both variant descriptions now say what the reader sees. Custom Hero's description drops the "COP tactical layouts / SITREP post headers" jargon for plain treatment names. blocks-core BLOCK_CATALOG mirror entries updated to match. Enum IDs (`sitrep1`, `cop1`…) and schema field names are unchanged, per the 71d3b09 purge discipline.
v0.15.9patch

71d3b09: Purge client-specific lore and Star Citizen universe references from all non-SC packages (content and labels only — no schema field names, slugs, or enum values changed). - **dispatch**: demo content rewritten as an incident-war-room / ops-bridge scenario (SEV-1 bridge traffic, failover runbooks, recovered security-report transcript) plus neutral original fiction for inherently fictional variants (Relay Station Aurelia personal log, SV Aurelia ship log). Config field-description examples de-lored (old client- and universe-specific labels → neutral equivalents). - **readout**: all 9 blocks' demo props rewritten as business-operations console data (deployment phases, sprint objectives, service status, perimeter traffic, on-call roster, infrastructure asset cards). Config examples de-lored. - **blocks-signal-theme**: demo props for the 33-block pack rewritten as an original search-and-rescue expedition serial ("Operation Long Wake", SV Aurelia, Meridian Reach) with zero client or SC references; config examples de-lored. Pack positioning (SC-tier bundling per OQ-4) unchanged. - **blocks-extras / blocks-content-writer**: Custom Hero and Post Hero meta descriptions stop name-dropping the client; "Callsign" field descriptions neutralized to "Author name or handle"; provenance comments neutralized. - **blocks-core**: BLOCK_CATALOG mirror entries refreshed for custom-hero and post-hero only; registry comment neutralized. - **blocks-gallery**: SourceBadge label for the `vngd` source value now renders "Legacy" (enum value unchanged). - **accounts / core / lms / ui / org / admin / motion / longform / cop / blocks**: internal provenance comments, shipped CSS comments, and consumer-visible field descriptions that named a specific client replaced with neutral "upstream" phrasing; longform package description de-lored. Historical CHANGELOG entries left untouched.

  • 71d3b09: Purge client-specific lore and Star Citizen universe references from all non-SC packages (content and labels only — no schema field names, slugs, or enum values changed). - **dispatch**: demo content rewritten as an incident-war-room / ops-bridge scenario (SEV-1 bridge traffic, failover runbooks, recovered security-report transcript) plus neutral original fiction for inherently fictional variants (Relay Station Aurelia personal log, SV Aurelia ship log). Config field-description examples de-lored (old client- and universe-specific labels → neutral equivalents). - **readout**: all 9 blocks' demo props rewritten as business-operations console data (deployment phases, sprint objectives, service status, perimeter traffic, on-call roster, infrastructure asset cards). Config examples de-lored. - **blocks-signal-theme**: demo props for the 33-block pack rewritten as an original search-and-rescue expedition serial ("Operation Long Wake", SV Aurelia, Meridian Reach) with zero client or SC references; config examples de-lored. Pack positioning (SC-tier bundling per OQ-4) unchanged. - **blocks-extras / blocks-content-writer**: Custom Hero and Post Hero meta descriptions stop name-dropping the client; "Callsign" field descriptions neutralized to "Author name or handle"; provenance comments neutralized. - **blocks-core**: BLOCK_CATALOG mirror entries refreshed for custom-hero and post-hero only; registry comment neutralized. - **blocks-gallery**: SourceBadge label for the `vngd` source value now renders "Legacy" (enum value unchanged). - **accounts / core / lms / ui / org / admin / motion / longform / cop / blocks**: internal provenance comments, shipped CSS comments, and consumer-visible field descriptions that named a specific client replaced with neutral "upstream" phrasing; longform package description de-lored. Historical CHANGELOG entries left untouched.
v0.15.8patch

6779aa1: Neutralize gaming/military-flavored language across the org surfaces — labels, descriptions, and demo content only; zero schema changes (all field names, collection slugs, and enum/select VALUES are byte-identical, so no consumer data migration). - **blocks-org-pack:** CampaignBanner's `codename` field is now labeled "Name" with a business example ("Spring Launch" demo replaces "Operation Nightfall … contested systems"); MemberCard/MemberGrid `rank` fields labeled "Role" with business-ladder demo values (Principal/Staff/Senior replace Captain/Lieutenant/Sergeant, "Fleet Commander" → "Design Lead"); EventCalendar demo uses business events (workshop, hiring open house, quarterly business review — "Upcoming Operations" heading → "Upcoming Events"); OrgChart meta/variants describe a generic three-level hierarchy instead of Division → Teams → Squads (render output was already 100% data-driven — level headings come from the authored rows, so no new props were needed); block meta descriptions/usage neutralized throughout. - **tome-org:** flavored admin LABELS get neutral text while stored values stay put — Event status `boarding`/`debrief` labeled "Check-In"/"Wrap-Up"; eventType `operation`/`patrol`/`exam` labeled "Initiative"/"Outreach"/"Assessment"; `securityLevel` labeled "Access"; Campaign `codename` labeled "Internal Name" and campaignType `recurring_op`/`special_operation`/`deployment` labeled "Recurring Series"/"Special Initiative"/"Rollout"; Member `classification` labeled "Directory Visibility" with `classified` labeled "Private", "Chain of command" → "Reporting line"; Rank `securityClearance` labeled "Access Level" and category `command` labeled "Management"; Squad squadType `fire_team`/`flight` labeled "Crew"/"Pod", `callsign` labeled "Nickname"; Membership `squadron` labeled "Unit", role example "Pointman, Medic" → "Coordinator, Facilitator"; Position abbreviation example "CO, XO" → "COO, PM", category `command` labeled "Executive". The configurable `DEFAULT_ORG_TERMINOLOGY` (Division/Team/Squad/Rank) is deliberately unchanged — it is the documented override seam and `@wabbit/tome-sc` inherits it for its themed collections. - **blocks-core:** BLOCK_CATALOG entries for campaign-banner, member-card, and org-chart re-mirror the updated pack meta descriptions (catalog is generated from pack meta; only the entries owned by this change were refreshed).

  • 6779aa1: Neutralize gaming/military-flavored language across the org surfaces — labels, descriptions, and demo content only; zero schema changes (all field names, collection slugs, and enum/select VALUES are byte-identical, so no consumer data migration). - **blocks-org-pack:** CampaignBanner's `codename` field is now labeled "Name" with a business example ("Spring Launch" demo replaces "Operation Nightfall … contested systems"); MemberCard/MemberGrid `rank` fields labeled "Role" with business-ladder demo values (Principal/Staff/Senior replace Captain/Lieutenant/Sergeant, "Fleet Commander" → "Design Lead"); EventCalendar demo uses business events (workshop, hiring open house, quarterly business review — "Upcoming Operations" heading → "Upcoming Events"); OrgChart meta/variants describe a generic three-level hierarchy instead of Division → Teams → Squads (render output was already 100% data-driven — level headings come from the authored rows, so no new props were needed); block meta descriptions/usage neutralized throughout. - **tome-org:** flavored admin LABELS get neutral text while stored values stay put — Event status `boarding`/`debrief` labeled "Check-In"/"Wrap-Up"; eventType `operation`/`patrol`/`exam` labeled "Initiative"/"Outreach"/"Assessment"; `securityLevel` labeled "Access"; Campaign `codename` labeled "Internal Name" and campaignType `recurring_op`/`special_operation`/`deployment` labeled "Recurring Series"/"Special Initiative"/"Rollout"; Member `classification` labeled "Directory Visibility" with `classified` labeled "Private", "Chain of command" → "Reporting line"; Rank `securityClearance` labeled "Access Level" and category `command` labeled "Management"; Squad squadType `fire_team`/`flight` labeled "Crew"/"Pod", `callsign` labeled "Nickname"; Membership `squadron` labeled "Unit", role example "Pointman, Medic" → "Coordinator, Facilitator"; Position abbreviation example "CO, XO" → "COO, PM", category `command` labeled "Executive". The configurable `DEFAULT_ORG_TERMINOLOGY` (Division/Team/Squad/Rank) is deliberately unchanged — it is the documented override seam and `@wabbit/tome-sc` inherits it for its themed collections. - **blocks-core:** BLOCK_CATALOG entries for campaign-banner, member-card, and org-chart re-mirror the updated pack meta descriptions (catalog is generated from pack meta; only the entries owned by this change were refreshed).
v0.15.0minor

510036f: Route pack block links through the `LinkAdapter` instead of raw `<a href>`. `LinkAdapter` (0.14.0) shipped the seam; this connects it. **67 anchors across 55 renderer files in 10 packs** now render through `<TomeLink>`, so a consuming site that registers a link adapter gets its route transition on pack blocks — previously impossible by construction, since a pack cannot import the consumer's transition component and the consumer cannot reach into a pack's render tree. **New in `@wabbit/tome-blocks-core`: `<TomeLink>`**, a component form of `resolveLink()`. `resolveRichText()` / `resolveMedia()` are functions because they turn a data value into content; a link _wraps children_, and the function form forces multi-line JSX through a `children:` prop. `<TomeLink href={…}>…</TomeLink>` is a drop-in for the `<a>` it replaces. It delegates to `resolveLink()`, so there is exactly one resolution path, and it stays directive-free so RSC pack renderers can use it without becoming client components. **`LinkProps.href` is now `string | null | undefined`.** Block data routinely carries an optional URL, and the raw `<a href={undefined}>` these calls replaced was legal markup. Narrowing it to `string` would have forced ~10 non-null assertions across the packs and changed behavior at each. `NOOP_LINK_ADAPTER` normalises null to `undefined` so React omits the attribute — the unregistered path stays byte-identical to the pre-adapter markup. **Behaviour is unchanged for every consumer that has not registered a link adapter**, which is currently all of them: `resolveLink` falls back to a plain `<a>`. Deliberately left as raw `<a>`: - `EditorialFootnotes` — its `#fnref-*` anchors are in-page backlinks. Client-routing them would play a page transition for a jump within the same document. - `PricingPlans` / `PricingPlanCard` — these already accept an injectable anchor component, a more expressive consumer mechanism that predates the adapter. - `LogoSlider` — a self-closing, childless `target="_blank"` overlay anchor. Always external, so the adapter would hand it straight back to the browser. - `@wabbit/tome-longform` — it has zero runtime dependencies and does not peer on `blocks-core`. Adding that edge to the layer graph is its own decision, not a sweep side effect.

  • 510036f: Route pack block links through the `LinkAdapter` instead of raw `<a href>`. `LinkAdapter` (0.14.0) shipped the seam; this connects it. **67 anchors across 55 renderer files in 10 packs** now render through `<TomeLink>`, so a consuming site that registers a link adapter gets its route transition on pack blocks — previously impossible by construction, since a pack cannot import the consumer's transition component and the consumer cannot reach into a pack's render tree. **New in `@wabbit/tome-blocks-core`: `<TomeLink>`**, a component form of `resolveLink()`. `resolveRichText()` / `resolveMedia()` are functions because they turn a data value into content; a link _wraps children_, and the function form forces multi-line JSX through a `children:` prop. `<TomeLink href={…}>…</TomeLink>` is a drop-in for the `<a>` it replaces. It delegates to `resolveLink()`, so there is exactly one resolution path, and it stays directive-free so RSC pack renderers can use it without becoming client components. **`LinkProps.href` is now `string | null | undefined`.** Block data routinely carries an optional URL, and the raw `<a href={undefined}>` these calls replaced was legal markup. Narrowing it to `string` would have forced ~10 non-null assertions across the packs and changed behavior at each. `NOOP_LINK_ADAPTER` normalises null to `undefined` so React omits the attribute — the unregistered path stays byte-identical to the pre-adapter markup. **Behaviour is unchanged for every consumer that has not registered a link adapter**, which is currently all of them: `resolveLink` falls back to a plain `<a>`. Deliberately left as raw `<a>`: - `EditorialFootnotes` — its `#fnref-*` anchors are in-page backlinks. Client-routing them would play a page transition for a jump within the same document. - `PricingPlans` / `PricingPlanCard` — these already accept an injectable anchor component, a more expressive consumer mechanism that predates the adapter. - `LogoSlider` — a self-closing, childless `target="_blank"` overlay anchor. Always external, so the adapter would hand it straight back to the browser. - `@wabbit/tome-longform` — it has zero runtime dependencies and does not peer on `blocks-core`. Adding that edge to the layer graph is its own decision, not a sweep side effect.
v0.14.0minor

Add `LinkAdapter` — the third block adapter, alongside `RichTextAdapter` and `MediaAdapter`. Every link-rendering block in every pack emits a raw `<a href>`, which is a full document load. A pack cannot import a consuming site's route-transition component (wrong layer direction), and a site cannot reach inside a pack's render tree to swap the anchor — so pack links could never participate in a consumer's page transition, by construction. ```ts registerBlockAdapters({ link: { Link: MyTransitionLink, isLinkActive: true }, }); resolveLink({ href: block.ctaUrl, className: styles.cta, children: text }); ``` Mirrors the existing adapters exactly: module registry + `'use client'` Context fallback, with `resolveLink` statically importing `LinkContextFallback` so the bundler cuts the client boundary at build time. **One deliberate divergence:** the unregistered default is fully functional, not a stub. `NOOP_LINK_ADAPTER` renders a real `<a>` and `resolveLink` never dev-warns. Rich text and media have no meaningful fallback, so their absence is always a misconfiguration. A link does have one: navigate. Losing the transition is degraded; losing the navigation is broken — so a plain anchor is a supported end state for a standalone pack. New exports: `resolveLink`, `LinkAdapterContext`, `LinkAdapterProvider`, `useLinkAdapter`, `NOOP_LINK_ADAPTER`, and the `LinkProps` / `LinkAdapter` types. `BlockAdapters` gains an optional `link` slot. **Fully additive** — no existing adapter, export, or block behavior changes. Pack renderer migration off raw `<a>` is a follow-up.

  • Add `LinkAdapter` — the third block adapter, alongside `RichTextAdapter` and `MediaAdapter`. Every link-rendering block in every pack emits a raw `<a href>`, which is a full document load. A pack cannot import a consuming site's route-transition component (wrong layer direction), and a site cannot reach inside a pack's render tree to swap the anchor — so pack links could never participate in a consumer's page transition, by construction. ```ts registerBlockAdapters({ link: { Link: MyTransitionLink, isLinkActive: true }, }); resolveLink({ href: block.ctaUrl, className: styles.cta, children: text }); ``` Mirrors the existing adapters exactly: module registry + `'use client'` Context fallback, with `resolveLink` statically importing `LinkContextFallback` so the bundler cuts the client boundary at build time. **One deliberate divergence:** the unregistered default is fully functional, not a stub. `NOOP_LINK_ADAPTER` renders a real `<a>` and `resolveLink` never dev-warns. Rich text and media have no meaningful fallback, so their absence is always a misconfiguration. A link does have one: navigate. Losing the transition is degraded; losing the navigation is broken — so a plain anchor is a supported end state for a standalone pack. New exports: `resolveLink`, `LinkAdapterContext`, `LinkAdapterProvider`, `useLinkAdapter`, `NOOP_LINK_ADAPTER`, and the `LinkProps` / `LinkAdapter` types. `BlockAdapters` gains an optional `link` slot. **Fully additive** — no existing adapter, export, or block behavior changes. Pack renderer migration off raw `<a>` is a follow-up.
v0.13.0minor

f4d55c9: render: shared `Reveal` (scroll-reveal client wrapper) + `renderEmphasis` (asterisk→em) helpers for showcase variant graduation. Ported verbatim from tome-starter's `src/components/Reveal` and `src/utilities/renderEmphasis` (showcase program Phase 3.7) so pack renderers graduating starter-native showcase variants (e.g. `@wabbit/tome-blocks-marketing-starter`'s cta `door-strip` / `doors`) can share them instead of vendoring copies. Both exported from the `./render` subpath.

  • f4d55c9: render: shared `Reveal` (scroll-reveal client wrapper) + `renderEmphasis` (asterisk→em) helpers for showcase variant graduation. Ported verbatim from tome-starter's `src/components/Reveal` and `src/utilities/renderEmphasis` (showcase program Phase 3.7) so pack renderers graduating starter-native showcase variants (e.g. `@wabbit/tome-blocks-marketing-starter`'s cta `door-strip` / `doors`) can share them instead of vendoring copies. Both exported from the `./render` subpath.
v0.11.2patch

e11d5a2: Fix `resolveMedia`/`resolveRichText` crashing pages with `TypeError: Cannot read properties of null (reading 'useContext')` during RSC render. Both resolvers preferred a "registered adapter fast path" — `createElement(getMediaAdapter().Media, …)` on a component read from the globalThis registry at runtime. A bundler cannot statically trace that runtime reference to the adapter's module, so it never cuts the RSC client-reference boundary for the component's subtree. When the registered `Media` renders an intrinsically-client primitive (`next/image`, which calls `useContext`), that primitive executes during the Flight serialization pass with a null dispatcher and throws — 500-ing any page whose **server** pack renderer (e.g. `editorialFigure`) resolves media. It reproduces even when the registered component itself carries `'use client'`; the boundary is defeated by the runtime `createElement`, not the directive. (Verified against wabbit-site-core `/static-site-launch`, 2026-07-15.) Both resolvers now ALWAYS defer to their statically-imported `'use client'` fallback component (`MediaContextFallback` / `RichTextContextFallback`), which the bundler CAN boundary at build time. Adapter resolution (Context override first, module registry second) moves into those components via new hook-free `resolveActiveMediaAdapter` / `resolveActiveRichTextAdapter` helpers, so both adapter sources still work, including for a server component with no provider ancestor. Consequence: media/rich-text now always render inside a client boundary (no zero-JS server-only path). This is unavoidable for any `next/image`-based adapter, which is intrinsically client — mirroring the spec's existing "motion is intrinsically client" carve-out. A future opt-in `isServerSafe` adapter flag could restore the zero-JS registry path for provably `<img>`-only adapters; it is deliberately not the default, because the default must be correct.

  • e11d5a2: Fix `resolveMedia`/`resolveRichText` crashing pages with `TypeError: Cannot read properties of null (reading 'useContext')` during RSC render. Both resolvers preferred a "registered adapter fast path" — `createElement(getMediaAdapter().Media, …)` on a component read from the globalThis registry at runtime. A bundler cannot statically trace that runtime reference to the adapter's module, so it never cuts the RSC client-reference boundary for the component's subtree. When the registered `Media` renders an intrinsically-client primitive (`next/image`, which calls `useContext`), that primitive executes during the Flight serialization pass with a null dispatcher and throws — 500-ing any page whose **server** pack renderer (e.g. `editorialFigure`) resolves media. It reproduces even when the registered component itself carries `'use client'`; the boundary is defeated by the runtime `createElement`, not the directive. (Verified against wabbit-site-core `/static-site-launch`, 2026-07-15.) Both resolvers now ALWAYS defer to their statically-imported `'use client'` fallback component (`MediaContextFallback` / `RichTextContextFallback`), which the bundler CAN boundary at build time. Adapter resolution (Context override first, module registry second) moves into those components via new hook-free `resolveActiveMediaAdapter` / `resolveActiveRichTextAdapter` helpers, so both adapter sources still work, including for a server component with no provider ancestor. Consequence: media/rich-text now always render inside a client boundary (no zero-JS server-only path). This is unavoidable for any `next/image`-based adapter, which is intrinsically client — mirroring the spec's existing "motion is intrinsically client" carve-out. A future opt-in `isServerSafe` adapter flag could restore the zero-JS registry path for provably `<img>`-only adapters; it is deliberately not the default, because the default must be correct.
v0.11.0patch

26dfa07: Pre-existing test-suite fixes (unrelated to recent feature work): - `high-impact-hero`'s `illustrationHero` variant carried two tags (`brand`, `illustration`) outside the canonical taxonomy declared in `v2-coverage.test.ts`. Fixed to `['editorial', 'playful']`. The `illustrationHero` slug itself is kept camelCase (not renamed to kebab-case) because it shipped in the published `0.5.0` release (2026-05-21) and is stored verbatim in consumer content as a `_variant` field value — renaming would silently break every stored document that already selected it. The kebab-case rule now carries a documented, slug-scoped exception with a deprecation trigger (next content-breaking major version for this package, when a stored-content migration pass is already budgeted). - `blocks-core`'s `test/top20-variants.test.ts` imported `@wabbit/tome-blocks-marketing-starter` and the other bundle packs directly, which a later refactor made unresolvable when it removed blocks-core's devDeps on those packs to break the blocks-core ↔ marketing-starter dependency cycle. Relocated the test to `@wabbit/tome-blocks` (the meta-package that already depends on every pack for exactly this purpose) rather than re-adding the removed devDeps and recreating the cycle. Test-only change; no runtime behavior changed in either package.

  • 26dfa07: Pre-existing test-suite fixes (unrelated to recent feature work): - `high-impact-hero`'s `illustrationHero` variant carried two tags (`brand`, `illustration`) outside the canonical taxonomy declared in `v2-coverage.test.ts`. Fixed to `['editorial', 'playful']`. The `illustrationHero` slug itself is kept camelCase (not renamed to kebab-case) because it shipped in the published `0.5.0` release (2026-05-21) and is stored verbatim in consumer content as a `_variant` field value — renaming would silently break every stored document that already selected it. The kebab-case rule now carries a documented, slug-scoped exception with a deprecation trigger (next content-breaking major version for this package, when a stored-content migration pass is already budgeted). - `blocks-core`'s `test/top20-variants.test.ts` imported `@wabbit/tome-blocks-marketing-starter` and the other bundle packs directly, which a later refactor made unresolvable when it removed blocks-core's devDeps on those packs to break the blocks-core ↔ marketing-starter dependency cycle. Relocated the test to `@wabbit/tome-blocks` (the meta-package that already depends on every pack for exactly this purpose) rather than re-adding the removed devDeps and recreating the cycle. Test-only change; no runtime behavior changed in either package.
  • 36e537a: Peer/dependency contracts now tell the truth. blocks-core: importing the root barrel no longer hard-crashes when the optional peers (`@wabbit/tome-core`, `@wabbit/tome-catalog`) are absent — `productHooks` registration is lazily guarded; NEW explicit `registerBlockBundleProductType()` export (root barrel + `./registry/productHooks` subpath) for deterministic, format-safe registration from `payload.config.ts` (the import-time auto path no-ops under native ESM, which affects `generate:types`-visible product-type options — call the explicit API when composing catalog). chrome: `next` is now a required peer (`>=14`) — it was declared optional while `next/navigation`/`next/link` were hard-imported. readout: declares its real `next` peer; `createReadoutBlocks({ accentPalette })` is now implemented (field-tree narrowing, dispatch's mechanism) instead of a documented no-op. blocks-lms-pack / blocks-catalog-pack: `@wabbit/tome-core` moves from hard `dependencies` to `optionalDependencies`, matching org-pack and the packs' own documented degrade-gracefully design.
  • 36e537a: Every package now declares an explicit `sideEffects` field (38 added; motion/engine/forms already correct). Registration-bearing modules (render files' `registerRenderer`, `blocks/*/index.ts` `defineBlock` self-registration, widget `register.ts` files, productHooks, permission self-registrations, print templates, chrome built-in variants) are listed so bundlers can tree-shake everything else WITHOUT dropping import-time registrations — previously the field was unset, which blocked cross-module tree-shaking through the barrels entirely. Never blanket `false` on a package with registration or CSS.
  • 36e537a: Small verified fixes: agency-essentials `Contact` gains its missing `'use client'` (it calls the rich-text adapter hook; direct RSC import crashed). chrome `NavGuard` now dev-warns when its capability gate fails to load while a `requiredCapability` is set (the fail-open contract itself is unchanged and now documented). blocks-core `BLOCK_CATALOG.ts` corrupted entries corrected from real block meta (content-two-column, content-with-corner-notch, signal-ship-card names/descriptions; gallery variants filled) + drift-risk header. Stale docstrings fixed (chrome `HeaderLogo`, blocks-gallery registry header, lms-ui payload JSDoc import path). blocks meta-package backcompat suite now asserts the RENDER registry resolves renderers (previously only descriptor registration was tested — a dropped render import shipped silently).
  • a93f478: Gallery browse performance: search input debounced at 80ms via a local-state + `useDebouncedValue` split (instant keystroke echo, one grid re-filter per pause; immune to context-sibling re-render stomps), `BlockCard` wrapped in `React.memo` (props verified referentially stable — unrelated re-renders no longer re-run every card's hover/visibility machinery). blocks-core publishes `./utilities/useDocumentTheme` as a lean subpath (mirroring `useDebouncedResize`) so Payload-free consumers can reach the theme hook without the admin barrel's `@payloadcms/ui` graph; gallery's local MutationObserver copy replaced with a narrowing wrapper over the canonical hook. Also: BlockPicker's artificial `setTimeout(0)` skeleton delay removed; RecentFavorites static data-attributes moved from an effect into JSX.
  • 5f78397: The clientization migration: 127 render components across seven packs dropped `'use client'` — every file individually re-verified hook/handler/context-free before stripping; adapter-consuming static blocks converted to `resolveRichText`/`resolveMedia`. Exactly 20 of 155 renderers remain client, each for a verified reason (state/effects/motion, or a documented client-shell composition contract), enforced by the new `assert:rsc-boundaries` CI script (per-pack manifest; fails loudly if a directive creeps back or a count drifts). Every renderer-bearing pack now exports `./render/register` (`renderers` map + explicit `registerRenderers()`), aggregated by `@wabbit/tome-blocks`'s new `registerAllRenderers()` — the format-safe registration path for server component graphs, where the legacy import-time barrel registration never executes (that legacy path is unchanged and remains supported until the spec's deprecation trigger). `RenderBlock` is rewritten server-safe: directive-free, optional `components` prop (RenderBlocks parity) → registry fallback, dev warn-once naming both fixes on a miss; its docs state the explicit-registration prerequisite. Rendered output is byte-identical everywhere; behavior change only for consumers rendering migrated blocks in RSC WITHOUT a provider or registration — they get the documented warn + graceful degradation instead of silent client bundling.
  • 5f78397: Server-safe adapter contract (spec 2026-07-12, waves M0–M1). blocks-core gains `./adapters`: `registerBlockAdapters({ richText?, media? })` (explicit, idempotent, lazily globalThis-anchored — layerRegistry pattern) plus environment-agnostic `resolveRichText(value, opts?)` / `resolveMedia(value, opts?)` callable from RSC and client alike. The adapter React Contexts now live in blocks-core (`adapters/context.tsx`); blocks-extras' adapter modules are thin re-exports (zero API break) and its Providers additionally sync their adapter into the registry (guarded write-during-render, documented). Unregistered-registry resolution returns a client fallback element that reads the Context — provider-based sites see zero behavior change even when migrated blocks execute as Server Components; sites that call `registerBlockAdapters` from a module in both graphs get pure server rendering. Migration contract for consumers: call `registerBlockAdapters` at config/app scope when adopting RSC-rendered blocks; the `useRichTextAdapter`/`useMediaAdapter` hooks remain functional (deprecated-in-place; removal trigger in the spec).
  • aef2725: DRY adoption sweep (the audit's "adoption, not extraction" rule): crm/deals capability presets delegate to core's `sessionHasCapabilityOrLegacyAdmin`; new core `buildOwnershipWhere`/`ownershipOrBypass` (via `./access`) adopted by core's vendorScoped, catalog's vendor-scoping, and org's ownOrScoped (public APIs unchanged); `slugField()` adopted at 7 sites where semantics matched exactly (core lms collections + createMemberCollection — replacing a third independent slugify), with ~25 sites honestly skipped for named semantic divergences (auto-regenerate-on-clear vs allow-empty, collection-level hook pattern) now listed as core-enhancement candidates; new `formatDisplayDate` in blocks-core utilities (UTC-pinned, hydration-safe) adopted at 5 verified-identical sites; lms-ui consolidates its two certificate date formatters locally; `useMediaQuery`/`useIsMobile` published from tome-ui and adopted by AppShell + admin's SidebarProvider; gamification's `awardPoints` now uses the authoritative `getPointsBalance` (fixes a divergent 1000-row scan cap vs the correct 10000).
v0.10.0minor

BlockPicker raster thumbnails: new GalleryThumbsProvider/ThumbnailSourceProvider API and thumbsManifestUrl prop render real gallery screenshot captures in the admin picker with a raster → authored SVG → placeholder fallback chain; shared useDocumentTheme utility; placeholder SVG migrated to canonical --tome-color-\* tokens.

  • BlockPicker raster thumbnails: new GalleryThumbsProvider/ThumbnailSourceProvider API and thumbsManifestUrl prop render real gallery screenshot captures in the admin picker with a raster → authored SVG → placeholder fallback chain; shared useDocumentTheme utility; placeholder SVG migrated to canonical --tome-color-\* tokens.
v0.9.4patch

bed3f90: Docs-manifest emitter pipeline (W3 ship-readiness). `@wabbit/tome-blocks-core` now ships a standalone Node ESM CLI at `scripts/emit-docs-manifests.mjs` that emits per-package documentation manifests (index.json, packages/<slug>.json, changelog.json) by reading what packages already carry — READMEs, the payload-free `<pkg>/meta` block-usage barrels, package.json exports maps, and CHANGELOG.md. It is the docs-pipeline sibling of the gallery source extractor and is consumed by host sites at prebuild: `node node_modules/@wabbit/tome-blocks-core/scripts/emit-docs-manifests.mjs --output-dir <dir> --scope <scope.json>`. To let the emitter import block metadata uniformly without dragging Payload config into a build script, the `./meta` payload-free subpath (BlockMetaEntry[]) is extended to the remaining offered blocks packs — agency-essentials, catalog-pack, lms-pack, org-pack, and signal-theme — mirroring the existing editorial-pack / marketing-starter / content-writer / extras barrels. Each block's `BlockMeta` was relocated verbatim into a payload-free sibling meta module and re-imported by its block config; no meta values changed. Every supported-core package additionally adds `CHANGELOG.md` to its published `files` array so the next publish cascade ships changelogs the emitter can read from installed tarballs at prebuild.

  • bed3f90: Docs-manifest emitter pipeline (W3 ship-readiness). `@wabbit/tome-blocks-core` now ships a standalone Node ESM CLI at `scripts/emit-docs-manifests.mjs` that emits per-package documentation manifests (index.json, packages/<slug>.json, changelog.json) by reading what packages already carry — READMEs, the payload-free `<pkg>/meta` block-usage barrels, package.json exports maps, and CHANGELOG.md. It is the docs-pipeline sibling of the gallery source extractor and is consumed by host sites at prebuild: `node node_modules/@wabbit/tome-blocks-core/scripts/emit-docs-manifests.mjs --output-dir <dir> --scope <scope.json>`. To let the emitter import block metadata uniformly without dragging Payload config into a build script, the `./meta` payload-free subpath (BlockMetaEntry[]) is extended to the remaining offered blocks packs — agency-essentials, catalog-pack, lms-pack, org-pack, and signal-theme — mirroring the existing editorial-pack / marketing-starter / content-writer / extras barrels. Each block's `BlockMeta` was relocated verbatim into a payload-free sibling meta module and re-imported by its block config; no meta values changed. Every supported-core package additionally adds `CHANGELOG.md` to its published `files` array so the next publish cascade ships changelogs the emitter can read from installed tarballs at prebuild.
v0.9.2patch

D3 breakout: additive optional `BlockMeta` fields `defaultBreakout`/`pinnedBand` for per-block breakout policy (`pinnedBand` is what the D6 Rule-D forward-tripwire guards).

  • D3 breakout: additive optional `BlockMeta` fields `defaultBreakout`/`pinnedBand` for per-block breakout policy (`pinnedBand` is what the D6 Rule-D forward-tripwire guards).
v0.9.0minor

c7d0afc: layoutGrid nesting capability audit + render hardening (Wave 2). Tags the `nestable` capability flag (and a `minColSpan` floor for internally-wide blocks) across the offered blocks in the core packs (extras, marketing, content, agency, editorial, signal), so the `layoutGrid` container's derived child allowlist — `blockRegistry.getNestableBlocks()` — is populated rather than empty. Excluded by design (left non-nestable): containers (`editorialSpread`, `editorialSection`, `split-view`, `stacking-wrapper`, `grid`, `layoutGrid`) to enforce the one-level depth cap; full-bleed heroes/banners (band-owners); and inline Lexical blocks (not block-level grid children). `minColSpan: 2` is set on the internally multi-column blocks (`card-grid`, `bento-section`, `content-two-column`, `signal-stats`, `signal-image-grid`, `signal-data-table`) so they cannot be crammed into a single-column cell. Also hardens `LayoutGrid`'s child↔span pairing: children are now flattened with null slots preserved (instead of `React.Children.toArray`, which drops nulls), so an unrenderable child can no longer shift every later child's span metadata onto the wrong block. Adds a dev-mode warning when the consumer's child count doesn't match the item count. `@wabbit/tome-blocks-core` is bumped to release the layoutGrid platform primitives merged earlier but never published (the registry's `0.8.0` predates that merge): `BlockMeta.nestable`/`minColSpan`, `withChildPlacement`, the reserved `_colSpan`/`_rowSpan`/`_order` field constants, and `blockRegistry.getNestableBlocks()`. Without this, a consumer wiring the layoutGrid allowlist would call a `getNestableBlocks` that its installed `blocks-core@0.8.0` does not have. Domain packs (lms, catalog, sc, org) are intentionally deferred — they compose into their own domain layouts and can opt in when a consumer needs them.

  • c7d0afc: layoutGrid nesting capability audit + render hardening (Wave 2). Tags the `nestable` capability flag (and a `minColSpan` floor for internally-wide blocks) across the offered blocks in the core packs (extras, marketing, content, agency, editorial, signal), so the `layoutGrid` container's derived child allowlist — `blockRegistry.getNestableBlocks()` — is populated rather than empty. Excluded by design (left non-nestable): containers (`editorialSpread`, `editorialSection`, `split-view`, `stacking-wrapper`, `grid`, `layoutGrid`) to enforce the one-level depth cap; full-bleed heroes/banners (band-owners); and inline Lexical blocks (not block-level grid children). `minColSpan: 2` is set on the internally multi-column blocks (`card-grid`, `bento-section`, `content-two-column`, `signal-stats`, `signal-image-grid`, `signal-data-table`) so they cannot be crammed into a single-column cell. Also hardens `LayoutGrid`'s child↔span pairing: children are now flattened with null slots preserved (instead of `React.Children.toArray`, which drops nulls), so an unrenderable child can no longer shift every later child's span metadata onto the wrong block. Adds a dev-mode warning when the consumer's child count doesn't match the item count. `@wabbit/tome-blocks-core` is bumped to release the layoutGrid platform primitives merged earlier but never published (the registry's `0.8.0` predates that merge): `BlockMeta.nestable`/`minColSpan`, `withChildPlacement`, the reserved `_colSpan`/`_rowSpan`/`_order` field constants, and `blockRegistry.getNestableBlocks()`. Without this, a consumer wiring the layoutGrid allowlist would call a `getNestableBlocks` that its installed `blocks-core@0.8.0` does not have. Domain packs (lms, catalog, sc, org) are intentionally deferred — they compose into their own domain layouts and can opt in when a consumer needs them.
v0.8.0minor

249b670: Batch 0 of the inserter/variant architecture (2026-06-27 spec): wire the variant picker onto `_variant` and ship the per-block usage/intent layer. - **Variant picker on `_variant`** — the auto-injected `_variant` field is no longer `admin.hidden`; it renders the thumbnail `VariantPickerField` (a new `useField` adapter exported from `/admin`), referenced by the `@wabbit/tome-blocks-core/admin` package path (lazy via importMap — never enters the config graph). `defineBlock` threads `blockSlug` + a serializable variant list through `clientProps`. This makes declared variants (e.g. `editorialSpread`'s 5) editor-reachable for the first time. Degrades to a native select when no thumbnails are ingested. - **Render-registry variant dimension** — `registerVariantRenderer` / `registerVariantRenderers` / `hasVariantRenderer` / `resolveRenderer` add a `{variant → component}` dispatch alongside the existing slug-keyed registry (additive, back-compat). - **Per-block usage/intent layer** — additive optional `BlockMeta.usage` (`BlockUsage`: summary / whenToUse / pageTypes / howToUse / pairsWith / sequence / avoidWhen / register) following the `requiresMotion`/`requiredCapabilities` precedent, plus a new `buildUsageManifest()` (`./usage` subpath) that flattens descriptors into a selection/sequencing index for assembling agents. Exemplar authored on `editorialSpread`. - Adds `@payloadcms/ui` as an **optional** peer dependency (only the `/admin` subpath needs it). Linked family aligns to 0.8.0. No breaking API changes (all additive; `_variant` becoming visible is a behavior change, not an API removal).

  • 249b670: Batch 0 of the inserter/variant architecture (2026-06-27 spec): wire the variant picker onto `_variant` and ship the per-block usage/intent layer. - **Variant picker on `_variant`** — the auto-injected `_variant` field is no longer `admin.hidden`; it renders the thumbnail `VariantPickerField` (a new `useField` adapter exported from `/admin`), referenced by the `@wabbit/tome-blocks-core/admin` package path (lazy via importMap — never enters the config graph). `defineBlock` threads `blockSlug` + a serializable variant list through `clientProps`. This makes declared variants (e.g. `editorialSpread`'s 5) editor-reachable for the first time. Degrades to a native select when no thumbnails are ingested. - **Render-registry variant dimension** — `registerVariantRenderer` / `registerVariantRenderers` / `hasVariantRenderer` / `resolveRenderer` add a `{variant → component}` dispatch alongside the existing slug-keyed registry (additive, back-compat). - **Per-block usage/intent layer** — additive optional `BlockMeta.usage` (`BlockUsage`: summary / whenToUse / pageTypes / howToUse / pairsWith / sequence / avoidWhen / register) following the `requiresMotion`/`requiredCapabilities` precedent, plus a new `buildUsageManifest()` (`./usage` subpath) that flattens descriptors into a selection/sequencing index for assembling agents. Exemplar authored on `editorialSpread`. - Adds `@payloadcms/ui` as an **optional** peer dependency (only the `/admin` subpath needs it). Linked family aligns to 0.8.0. No breaking API changes (all additive; `_variant` becoming visible is a behavior change, not an API removal).
v0.7.0minor

66c611c: B1 — block tiering formalization + blocks-extras free/paid split. - **blocks-core:** add `'addon'` to the `BundleMeta.tier` union (additive; existing `'pro'` values stay valid). - **blocks-extras:** register TWO bundles from one package (Option B) — a free `extras-primitives` sub-bundle (9 structural primitives) + the paid `extras` remainder (39 blocks, was 48). Mechanically additive: no import-path changes, all blocks still exported + registered, existing content keeps rendering, existing `extras` entitlements keep working (the primitives are now free to everyone). The tier-scope change is the only semantic shift. - **signal-theme + sc-pack:** tier `'pro'` → `'addon'` (sold independently of the tiered subscription track). - **blocks-gallery:** widen the `@wabbit/tome-blocks-core` peer to `^0.5.9 || ^0.6.0 || ^0.7.0` so the 0.7.0 bump doesn't force a spurious major (it's a types-only peer). Patch. Release note: the blocks family is `linked`, so this aligns the whole family to **0.7.0**. Minor (not major) is deliberate — 0.7.0 still gates explicit consumer adoption (`^0.6` does not auto-resolve 0.7.0), without declaring a symbolic 1.0.0 before the marketplace launch.

  • 66c611c: B1 — block tiering formalization + blocks-extras free/paid split. - **blocks-core:** add `'addon'` to the `BundleMeta.tier` union (additive; existing `'pro'` values stay valid). - **blocks-extras:** register TWO bundles from one package (Option B) — a free `extras-primitives` sub-bundle (9 structural primitives) + the paid `extras` remainder (39 blocks, was 48). Mechanically additive: no import-path changes, all blocks still exported + registered, existing content keeps rendering, existing `extras` entitlements keep working (the primitives are now free to everyone). The tier-scope change is the only semantic shift. - **signal-theme + sc-pack:** tier `'pro'` → `'addon'` (sold independently of the tiered subscription track). - **blocks-gallery:** widen the `@wabbit/tome-blocks-core` peer to `^0.5.9 || ^0.6.0 || ^0.7.0` so the 0.7.0 bump doesn't force a spurious major (it's a types-only peer). Patch. Release note: the blocks family is `linked`, so this aligns the whole family to **0.7.0**. Minor (not major) is deliberate — 0.7.0 still gates explicit consumer adoption (`^0.6` does not auto-resolve 0.7.0), without declaring a symbolic 1.0.0 before the marketplace launch.
v0.6.2patch

4b2f368: Platform-wide peer-range sweep: every `workspace:*`/`workspace:^` entry in `peerDependencies` replaced with an explicit semver range (`@wabbit/tome-core >=1.0.0 <2.0.0`, `tome-ui >=0.9.0 <1.0.0`, `tome-motion >=0.2.0 <1.0.0`, `tome-catalog >=1.1.0 <2.0.0`, `tome-admin >=0.5.0 <1.0.0`; `tome-crm` ranges standardized to `>=0.2.0 <1.0.0`). The workspace protocol publishes as an **exact-version pin**, so every substrate bump stranded installed dependents — the breakage class proven by marketing@0.1.0/deals@0.1.1 requiring `tome-crm@0.2.0` exactly. devDependencies keep `workspace:*` for the local link. (`@wabbit/tome-admin-pro` got the same source fix but is rc-versioned; it carries the change on its next intentional release.) tome-crm additionally gains a once-per-process **production warning when the capability-registry fallback grants access** — the bootstrap heuristic (any authenticated user passes `crm:read`) now announces itself instead of running silently on sites that forgot to seed capability grants (2026-06-10 audit hardening item). Graph-truth additions (same hygiene wave): tome-deals declares its lazy print integration as an optional peer (`@wabbit/tome-print >=0.1.0 <1.0.0`); tome-intake declares its lazy catalog routing strategy (`@wabbit/tome-catalog >=1.1.0 <2.0.0`, optional). These were undeclared dynamic imports — invisible to consumers and to pnpm's build topology.

  • 4b2f368: Platform-wide peer-range sweep: every `workspace:*`/`workspace:^` entry in `peerDependencies` replaced with an explicit semver range (`@wabbit/tome-core >=1.0.0 <2.0.0`, `tome-ui >=0.9.0 <1.0.0`, `tome-motion >=0.2.0 <1.0.0`, `tome-catalog >=1.1.0 <2.0.0`, `tome-admin >=0.5.0 <1.0.0`; `tome-crm` ranges standardized to `>=0.2.0 <1.0.0`). The workspace protocol publishes as an **exact-version pin**, so every substrate bump stranded installed dependents — the breakage class proven by marketing@0.1.0/deals@0.1.1 requiring `tome-crm@0.2.0` exactly. devDependencies keep `workspace:*` for the local link. (`@wabbit/tome-admin-pro` got the same source fix but is rc-versioned; it carries the change on its next intentional release.) tome-crm additionally gains a once-per-process **production warning when the capability-registry fallback grants access** — the bootstrap heuristic (any authenticated user passes `crm:read`) now announces itself instead of running silently on sites that forgot to seed capability grants (2026-06-10 audit hardening item). Graph-truth additions (same hygiene wave): tome-deals declares its lazy print integration as an optional peer (`@wabbit/tome-print >=0.1.0 <1.0.0`); tome-intake declares its lazy catalog routing strategy (`@wabbit/tome-catalog >=1.1.0 <2.0.0`, optional). These were undeclared dynamic imports — invisible to consumers and to pnpm's build topology.
v0.5.9patch

Updated dependencies [8947ff1] - @wabbit/tome-core@1.0.12 - @wabbit/tome-catalog@1.1.3

  • Updated dependencies [8947ff1] - @wabbit/tome-core@1.0.12 - @wabbit/tome-catalog@1.1.3
v0.5.7patch

Updated dependencies [36dc023]

  • Updated dependencies [36dc023]
  • Updated dependencies [2612799] - @wabbit/tome-core@1.0.11 - @wabbit/tome-catalog@1.1.2
v0.5.1patch

Add a `./fields/columnSpan` export to the package `exports` map so registry consumers can import the shared `columnSpan` field factory directly. Under path-alias consumption the deep path resolved against source; the `exports` map enforces it under registry consumption. Surfaced by tome-starter's `Section/config.ts` during the move to registry consumption.

  • Add a `./fields/columnSpan` export to the package `exports` map so registry consumers can import the shared `columnSpan` field factory directly. Under path-alias consumption the deep path resolved against source; the `exports` map enforces it under registry consumption. Surfaced by tome-starter's `Section/config.ts` during the move to registry consumption.
v0.5.0minor

Linked cohort version alignment (no functional change in this package).

  • Linked cohort version alignment (no functional change in this package).
v0.4.2patch

**Re-publish: rewrite `workspace:*` to actual semver in dependencies.** Earlier 0.4.0/0.4.1 publishes used `npm publish` directly, which doesn't rewrite `workspace:*` deps. Verdaccio captured the literal `"workspace:*"` strings in the published `package.json` `dependencies` fields, so npm consumers (e.g. wabbit-site-core) failed to install with `EUNSUPPORTEDPROTOCOL workspace:*`. This changeset triggers a coordinated patch bump across the linked blocks-_ group (already 0.4.1 → 0.4.2) plus motion, lms-pack, catalog-pack, and the previously-untouched blocks-core. Re-publish flow uses `pnpm publish` which rewrites `workspace:_` to the actual version of the workspace dep at publish time. No source changes — purely a publish-pipeline correction.

  • **Re-publish: rewrite `workspace:*` to actual semver in dependencies.** Earlier 0.4.0/0.4.1 publishes used `npm publish` directly, which doesn't rewrite `workspace:*` deps. Verdaccio captured the literal `"workspace:*"` strings in the published `package.json` `dependencies` fields, so npm consumers (e.g. wabbit-site-core) failed to install with `EUNSUPPORTEDPROTOCOL workspace:*`. This changeset triggers a coordinated patch bump across the linked blocks-_ group (already 0.4.1 → 0.4.2) plus motion, lms-pack, catalog-pack, and the previously-untouched blocks-core. Re-publish flow uses `pnpm publish` which rewrites `workspace:_` to the actual version of the workspace dep at publish time. No source changes — purely a publish-pipeline correction.
v0.4.0minor

b76f684: **Register `block-bundle` as a Tier 1 product type + wire Tier 2 `getCardFields` hook.** `@wabbit/tome-blocks-core` now self-registers `block-bundle` in `@wabbit/tome-catalog`'s `productTypeRegistry` at module-load (mirrors the catalog defaults pattern). Bundles previously lived only in the in-memory `BundleRegistry`; they now appear in catalog admin's product type dropdown. Also wires a `getCardFields` hook against `@wabbit/tome-core/registry/productTypeHookRegistry` for slug `'block-bundle'`. The hook resolves linked bundles via `catalog-products.metadata.bundleSlug` → `bundleRegistry.get(slug)` (a new platform convention — documented in this changeset; will graduate to spec when a 2nd consumer adopts). Returns enriched card fields (`Bundle · N blocks` badge, block count metadata) when the bundle is registered; degrades gracefully with product-only fields otherwise.

  • b76f684: **Register `block-bundle` as a Tier 1 product type + wire Tier 2 `getCardFields` hook.** `@wabbit/tome-blocks-core` now self-registers `block-bundle` in `@wabbit/tome-catalog`'s `productTypeRegistry` at module-load (mirrors the catalog defaults pattern). Bundles previously lived only in the in-memory `BundleRegistry`; they now appear in catalog admin's product type dropdown. Also wires a `getCardFields` hook against `@wabbit/tome-core/registry/productTypeHookRegistry` for slug `'block-bundle'`. The hook resolves linked bundles via `catalog-products.metadata.bundleSlug` → `bundleRegistry.get(slug)` (a new platform convention — documented in this changeset; will graduate to spec when a 2nd consumer adopts). Returns enriched card fields (`Bundle · N blocks` badge, block count metadata) when the bundle is registered; degrades gracefully with product-only fields otherwise.
v0.3.0minor

f2202cd: Sprint 3 blocks split — v0.2.0 Extracted the Tome blocks monolith (@wabbit/tome-blocks) into independently publishable bundle packages. Each bundle is independently installable, tree-shakeable, and testable in isolation. **New packages (all v0.2.0):** - `@wabbit/tome-blocks-core` — registries, defineBlock/defineBundle, variants, thumbnails, admin components (BlockPicker, VariantPicker) - `@wabbit/tome-blocks-marketing-starter` (free) — 8 marketing blocks: Hero, FeatureHero, CTA, LogoSlider, Pricing, Testimonial, FAQ, Banner - `@wabbit/tome-blocks-content-writer` (free) — 10 editorial blocks: Blog, Archive, PostHero, RelatedPosts, EditorialOpener, EditorialBridge, EditorialSidenote, EditorialFigure, EditorialColophon, EditorialFootnotes - `@wabbit/tome-blocks-agency-essentials` (starter) — 10 agency blocks: About, Contact/Form, Gallery, Media, SplitView, Stat, StatBar, TeamRoster, Timeline - `@wabbit/tome-blocks-editorial-pack` (pro) — 8 editorial blocks: DataHero, Feature, InfoPanel, MessagePanel, MetricStrip, SplitPanel, StatusBoard, TextReveal - `@wabbit/tome-blocks-signal-theme` (pro) — 33 Signal narrative blocks - `@wabbit/tome-blocks-lms-pack` (pro) — scaffold for LMS blocks (Wave 3) - `@wabbit/tome-blocks-catalog-pack` (pro) — scaffold for catalog/ecommerce blocks (Wave 3) - `@wabbit/tome-blocks-sc-pack` (niche) — scaffold for Star Citizen blocks (Wave 3) - `@wabbit/tome-blocks-extras` (pro) — 47 residual blocks (heroes, layout, content, marketing) **@wabbit/tome-blocks is now a meta-package** that re-exports all bundle packages and provides `registerAll(blockRegistry, bundleRegistry)` as a convenience function. **Render colocation:** All 113 render `.tsx` components migrated from the monolith into their owning bundle packages (`./render` subpath on each bundle). **Breaking changes (internal):** - `@wabbit/tome-blocks/blocks` and `@wabbit/tome-blocks/bundles` subpaths removed (were Sprint 2 shims) - `packages/blocks/src/render/` category index files removed (replaced by per-bundle `./render` subpaths) **Migration:** ```ts // Before (monolith singleton, all blocks loaded) import "@wabbit/tome-blocks"; // After (explicit registration, tree-shakeable) import { blockRegistry, bundleRegistry, } from "@wabbit/tome-blocks-core/registry"; import { register } from "@wabbit/tome-blocks-marketing-starter"; register(blockRegistry, bundleRegistry); // Or use the meta-package convenience function import { blockRegistry, bundleRegistry, registerAll, } from "@wabbit/tome-blocks"; registerAll(blockRegistry, bundleRegistry); ```

  • f2202cd: Sprint 3 blocks split — v0.2.0 Extracted the Tome blocks monolith (@wabbit/tome-blocks) into independently publishable bundle packages. Each bundle is independently installable, tree-shakeable, and testable in isolation. **New packages (all v0.2.0):** - `@wabbit/tome-blocks-core` — registries, defineBlock/defineBundle, variants, thumbnails, admin components (BlockPicker, VariantPicker) - `@wabbit/tome-blocks-marketing-starter` (free) — 8 marketing blocks: Hero, FeatureHero, CTA, LogoSlider, Pricing, Testimonial, FAQ, Banner - `@wabbit/tome-blocks-content-writer` (free) — 10 editorial blocks: Blog, Archive, PostHero, RelatedPosts, EditorialOpener, EditorialBridge, EditorialSidenote, EditorialFigure, EditorialColophon, EditorialFootnotes - `@wabbit/tome-blocks-agency-essentials` (starter) — 10 agency blocks: About, Contact/Form, Gallery, Media, SplitView, Stat, StatBar, TeamRoster, Timeline - `@wabbit/tome-blocks-editorial-pack` (pro) — 8 editorial blocks: DataHero, Feature, InfoPanel, MessagePanel, MetricStrip, SplitPanel, StatusBoard, TextReveal - `@wabbit/tome-blocks-signal-theme` (pro) — 33 Signal narrative blocks - `@wabbit/tome-blocks-lms-pack` (pro) — scaffold for LMS blocks (Wave 3) - `@wabbit/tome-blocks-catalog-pack` (pro) — scaffold for catalog/ecommerce blocks (Wave 3) - `@wabbit/tome-blocks-sc-pack` (niche) — scaffold for Star Citizen blocks (Wave 3) - `@wabbit/tome-blocks-extras` (pro) — 47 residual blocks (heroes, layout, content, marketing) **@wabbit/tome-blocks is now a meta-package** that re-exports all bundle packages and provides `registerAll(blockRegistry, bundleRegistry)` as a convenience function. **Render colocation:** All 113 render `.tsx` components migrated from the monolith into their owning bundle packages (`./render` subpath on each bundle). **Breaking changes (internal):** - `@wabbit/tome-blocks/blocks` and `@wabbit/tome-blocks/bundles` subpaths removed (were Sprint 2 shims) - `packages/blocks/src/render/` category index files removed (replaced by per-bundle `./render` subpaths) **Migration:** ```ts // Before (monolith singleton, all blocks loaded) import "@wabbit/tome-blocks"; // After (explicit registration, tree-shakeable) import { blockRegistry, bundleRegistry, } from "@wabbit/tome-blocks-core/registry"; import { register } from "@wabbit/tome-blocks-marketing-starter"; register(blockRegistry, bundleRegistry); // Or use the meta-package convenience function import { blockRegistry, bundleRegistry, registerAll, } from "@wabbit/tome-blocks"; registerAll(blockRegistry, bundleRegistry); ```