@riverbankcms/sdk 0.1.0

package/README.md

@@ -0,0 +1,1892 @@
+# @riverbankcms/sdk
+
+A lightweight TypeScript SDK for consuming Riverbank CMS content in React Server Components, Next.js, and client-side React applications.
+
+## Features
+
+- ✅ **Server-side rendering** with `loadPage()` helper
+- ✅ **Unified content fetching** with `loadContent()` for pages and entries
+- ✅ **Client-side data fetching** with `usePage()` and `useContent()` hooks
+- ✅ **Automatic data prefetching** for blocks with loaders
+- ✅ **Custom block data loaders** - Config-based (CMS endpoints) and code-based (external APIs)
+- ✅ **Type-safe API client** with caching
+- ✅ **React Server Components** compatible
+- ✅ **Custom blocks** - Define site-specific blocks with full CMS editing support
+
+## Installation
+
+```bash
+npm install @riverbankcms/sdk
+# or
+pnpm add @riverbankcms/sdk
+```
+
+## Quick Start
+
+> **Important:** The `baseUrl` parameter must be the complete API URL including the `/api` path. For example: `https://dashboard.example.com/api`
+
+### Server-Side Rendering (Recommended)
+
+Use in Next.js App Router Server Components or getServerSideProps:
+
+```tsx
+import { createRiverbankClient, loadPage, Page } from '@riverbankcms/sdk';
+
+// Note: baseUrl must include the /api path
+const client = createRiverbankClient({
+  apiKey: process.env.RIVERBANK_API_KEY!,
+  baseUrl: process.env.NEXT_PUBLIC_DASHBOARD_URL + '/api',
+});
+
+export default async function HomePage() {
+  // Fetch all page data (site, page, block data) in parallel
+  const pageData = await loadPage({
+    client,
+    siteId: 'your-site-id',
+    path: '/',
+  });
+
+  return <Page {...pageData} />;
+}
+```
+
+### Client-Side Rendering
+
+For client-only React apps or Client Components:
+
+```tsx
+"use client";
+
+import { createRiverbankClient } from '@riverbankcms/sdk';
+import { usePage, Page } from '@riverbankcms/sdk/client';
+
+const client = createRiverbankClient({
+  apiKey: process.env.NEXT_PUBLIC_RIVERBANK_API_KEY!,
+  baseUrl: process.env.NEXT_PUBLIC_DASHBOARD_URL + '/api',
+});
+
+export function DynamicPage({ path }: { path: string }) {
+  const pageData = usePage({ client, siteId: 'your-site-id', path });
+
+  if (pageData.loading) return <div>Loading...</div>;
+  if (pageData.error) return <div>Error: {pageData.error.message}</div>;
+
+  return <Page {...pageData} />;
+}
+```
+
+## API Reference
+
+### Configuration
+
+```ts
+const client = createRiverbankClient({
+  apiKey: string;        // Required: Builder API key
+  baseUrl: string;       // Required: Full API URL (e.g., 'https://dashboard.example.com/api')
+  cache?: {
+    enabled?: boolean;   // Default: true
+    ttl?: number;        // Default: 300 (seconds)
+    maxSize?: number;    // Default: 100
+  };
+});
+```
+
+### Server-Side API
+
+```tsx
+import { loadPage, Page } from '@riverbankcms/sdk';
+
+// Fetch all page data
+const pageData = await loadPage({
+  client,
+  siteId: string,
+  path: string,
+  preview?: boolean,           // Default: false - set true for draft content
+  pageId?: string,             // Optional: explicit page ID
+  dataLoaderOverrides?: {      // Optional: code-based data loaders for custom blocks
+    'custom.block-id': {
+      loaderKey: async (ctx) => fetchData(ctx.content.fieldValue),
+    },
+  },
+});
+
+// Render the page
+<Page {...pageData} />
+```
+
+### Preview Mode (Draft Content)
+
+The SDK supports fetching draft/unpublished content by passing `preview: true`. This requires an API key with site access.
+
+**Server-Side Preview:**
+
+```tsx
+// app/preview/[[...slug]]/page.tsx
+import { createRiverbankClient, loadPage, Page } from '@riverbankcms/sdk';
+
+const client = createRiverbankClient({
+  apiKey: process.env.RIVERBANK_API_KEY!,
+  baseUrl: process.env.NEXT_PUBLIC_DASHBOARD_URL + '/api',
+});
+
+export default async function PreviewPage({ params, searchParams }) {
+  const pageData = await loadPage({
+    client,
+    siteId: searchParams.siteId,
+    path: `/${params.slug?.join('/') || ''}`,
+    preview: true, // 🔑 Fetch draft content
+  });
+
+  return (
+    <div>
+      <div className="preview-banner">Preview Mode - Draft Content</div>
+      <Page {...pageData} />
+    </div>
+  );
+}
+```
+
+**Client-Side Preview:**
+
+```tsx
+"use client";
+
+import { createRiverbankClient } from '@riverbankcms/sdk';
+import { usePage, Page } from '@riverbankcms/sdk/client';
+
+const client = createRiverbankClient({
+  apiKey: process.env.NEXT_PUBLIC_RIVERBANK_API_KEY!,
+  baseUrl: process.env.NEXT_PUBLIC_DASHBOARD_URL + '/api',
+});
+
+export function PreviewPage({ siteId, path }: { siteId: string; path: string }) {
+  const pageData = usePage({
+    client,
+    siteId,
+    path,
+    preview: true, // 🔑 Fetch draft content
+  });
+
+  if (pageData.loading) return <div>Loading preview...</div>;
+  if (pageData.error) return <div>Error: {pageData.error.message}</div>;
+
+  return <Page {...pageData} />;
+}
+```
+
+**How Preview Works:**
+
+- ✅ Uses your existing API key (no separate preview tokens needed)
+- ✅ Returns draft content for blocks (via `draftContent` field)
+- ✅ Shows unpublished pages that are in draft state
+- ✅ Published and preview content are cached separately
+- ✅ Requires API key to be scoped to the site
+
+**Use Cases:**
+
+- Preview pages before publishing
+- Share draft content with stakeholders
+- Test content changes in staging environment
+- Content editing workflows
+
+### Client-Side API
+
+```tsx
+import { usePage, Page } from '@riverbankcms/sdk/client';
+
+const pageData = usePage({
+  client,
+  siteId: string,
+  path: string,
+  preview?: boolean,  // Default: false - set true for draft content
+  pageId?: string,
+});
+
+// pageData is a discriminated union:
+// { loading: true, error: null, ... } |
+// { loading: false, error: Error, ... } |
+// { loading: false, error: null, page, theme, ... }
+```
+
+## Unified Content Loading (Pages + Entries)
+
+When a path might resolve to either a page or a content entry (blog post, product, etc.), use `loadContent()` or `useContent()` instead of the page-specific functions.
+
+### Server-Side: loadContent
+
+```tsx
+import { loadContent, isPageContent, Page } from '@riverbankcms/sdk';
+
+export default async function DynamicRoute({ params }) {
+  const path = `/${params.slug?.join('/') || ''}`;
+
+  const content = await loadContent({
+    client,
+    siteId: 'your-site-id',
+    path,
+    preview: false, // Set true for draft content
+  });
+
+  // Pages get rendered with the Page component
+  if (isPageContent(content)) {
+    return <Page {...content} />;
+  }
+
+  // Entries get rendered with custom UI
+  return (
+    <article>
+      <h1>{content.entry.title}</h1>
+      <div>{JSON.stringify(content.entry.content)}</div>
+    </article>
+  );
+}
+```
+
+### Client-Side: useContent
+
+```tsx
+"use client";
+
+import { useContent, isPageContentResult, Page } from '@riverbankcms/sdk/client';
+
+export function DynamicContent({ path }: { path: string }) {
+  const content = useContent({
+    client,
+    siteId: 'your-site-id',
+    path,
+    preview: false,
+  });
+
+  if (content.loading) return <div>Loading...</div>;
+  if (content.error) return <div>Error: {content.error.message}</div>;
+
+  if (isPageContentResult(content)) {
+    return <Page page={content.page} theme={content.theme} siteId={content.siteId} resolvedData={content.resolvedData} />;
+  }
+
+  // Render entry with custom UI
+  return (
+    <article>
+      <h1>{content.entry.title}</h1>
+      <p>Type: {content.entry.type}</p>
+      <div>{JSON.stringify(content.entry.content)}</div>
+    </article>
+  );
+}
+```
+
+### Entry-Specific Rendering
+
+Route entries to different components based on their content type:
+
+```tsx
+import { loadContent, isPageContent, Page } from '@riverbankcms/sdk';
+
+export default async function DynamicRoute({ params }) {
+  const content = await loadContent({ client, siteId, path: `/${params.slug?.join('/') || ''}` });
+
+  if (isPageContent(content)) {
+    return <Page {...content} />;
+  }
+
+  // Route to type-specific components
+  switch (content.entry.type) {
+    case 'blog-post':
+      return <BlogPost entry={content.entry} theme={content.theme} />;
+    case 'product':
+      return <ProductPage entry={content.entry} theme={content.theme} />;
+    case 'event':
+      return <EventPage entry={content.entry} theme={content.theme} />;
+    default:
+      return <GenericEntry entry={content.entry} />;
+  }
+}
+
+function BlogPost({ entry, theme }) {
+  const { title, content, metaDescription } = entry;
+  return (
+    <article>
+      <h1>{title}</h1>
+      <p className="lead">{metaDescription}</p>
+      <div className="prose">{content.body}</div>
+      <p>By {content.author} on {new Date(entry.createdAt).toLocaleDateString()}</p>
+    </article>
+  );
+}
+```
+
+### ContentEntryData Type
+
+When working with entries, you receive raw content data:
+
+```ts
+type ContentEntryData = {
+  id: string;
+  type: string | null;        // Content type key (e.g., 'blog-post', 'product')
+  title: string;
+  slug: string | null;
+  path: string | null;
+  status: string;
+  publishAt: string | null;
+  content: Record<string, unknown>;  // Raw content fields
+  metaTitle: string | null;
+  metaDescription: string | null;
+  createdAt: string;
+  updatedAt: string;
+};
+```
+
+### When to Use Which Function
+
+| Function | Use Case |
+|----------|----------|
+| `loadPage()` / `usePage()` | Pages only - throws error on entries |
+| `loadContent()` / `useContent()` | Both pages and entries - discriminated union |
+
+## Fetching Multiple Entries
+
+Use `client.getEntries()` to fetch lists of content entries for blog listing pages, product catalogs, etc.
+
+### Basic Usage
+
+```tsx
+import { createRiverbankClient } from '@riverbankcms/sdk';
+
+const client = createRiverbankClient({
+  apiKey: process.env.RIVERBANK_API_KEY!,
+  baseUrl: process.env.NEXT_PUBLIC_DASHBOARD_URL + '/api',
+});
+
+// Fetch all published blog posts
+const { entries } = await client.getEntries({
+  siteId: 'your-site-id',
+  contentType: 'blog-post',
+});
+```
+
+### Pagination and Sorting
+
+```tsx
+// Fetch latest 10 posts (newest first)
+const { entries: latestPosts } = await client.getEntries({
+  siteId: 'your-site-id',
+  contentType: 'blog-post',
+  limit: 10,
+  order: 'newest',
+});
+
+// Fetch oldest posts first (for archives)
+const { entries: archivedPosts } = await client.getEntries({
+  siteId: 'your-site-id',
+  contentType: 'blog-post',
+  order: 'oldest',
+});
+
+// Include draft entries for preview mode
+const { entries: allPosts } = await client.getEntries({
+  siteId: 'your-site-id',
+  contentType: 'blog-post',
+  preview: true, // Includes unpublished drafts
+});
+```
+
+### Parameters
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `siteId` | string | Yes | Site ID |
+| `contentType` | string | Yes | Content type key (e.g., 'blog-post') |
+| `limit` | number | No | Maximum entries to return |
+| `order` | 'newest' \| 'oldest' | No | Sort by publish date |
+| `preview` | boolean | No | Include draft entries |
+
+### Real-World Example: Blog Listing Page
+
+```tsx
+// app/blog/page.tsx
+import { createRiverbankClient } from '@riverbankcms/sdk';
+import Link from 'next/link';
+
+const client = createRiverbankClient({
+  apiKey: process.env.RIVERBANK_API_KEY!,
+  baseUrl: process.env.NEXT_PUBLIC_DASHBOARD_URL + '/api',
+});
+
+export default async function BlogPage() {
+  const site = await client.getSite({ slug: 'my-site' });
+
+  const { entries: posts } = await client.getEntries({
+    siteId: site.site.id,
+    contentType: 'blog-post',
+    limit: 10,
+    order: 'newest',
+  });
+
+  return (
+    <main>
+      <h1>Blog</h1>
+      <div className="grid gap-6">
+        {posts.map((post) => (
+          <article key={post.id}>
+            <Link href={`/blog/${post.slug}`}>
+              <h2>{post.title}</h2>
+            </Link>
+            <p>{post.metaDescription}</p>
+            <time>{post.publishedAt ? new Date(post.publishedAt).toLocaleDateString() : 'Draft'}</time>
+          </article>
+        ))}
+      </div>
+    </main>
+  );
+}
+```
+
+## Import Patterns
+
+⚠️ **Important:** Use the correct import path for your environment:
+
+```tsx
+// ✅ Server Components (Next.js App Router)
+import { createRiverbankClient, loadPage, Page } from '@riverbankcms/sdk';
+
+// ✅ Client Components (use "use client" directive)
+"use client";
+import { usePage, Page } from '@riverbankcms/sdk/client';
+```
+
+The `/client` subpath exports React hooks that require client-side React features (useState, useEffect). The main entry point only exports server-safe code.
+
+## Layout Component
+
+The `Layout` component renders the site header, footer, and wraps your page content. Use this when you want consistent site chrome across all pages.
+
+### Using Layout with Pre-Fetched Site Data
+
+When you already have site data (from `loadPage` or `client.getSite`):
+
+```tsx
+import { Layout } from '@riverbankcms/sdk';
+
+export default async function MyPage() {
+  const siteData = await client.getSite({ slug: 'my-site' });
+
+  return (
+    <Layout siteData={siteData}>
+      <main>
+        <h1>My Custom Page</h1>
+        <p>This content is wrapped with site header and footer.</p>
+      </main>
+    </Layout>
+  );
+}
+```
+
+### Automatic Site Fetching
+
+Layout can fetch site data automatically if you provide a client and identifier:
+
+```tsx
+import { Layout } from '@riverbankcms/sdk';
+
+export default async function MyPage() {
+  return (
+    <Layout
+      client={client}
+      slug="my-site"  // or siteId="..." or domain="example.com"
+    >
+      <main>
+        <h1>My Custom Page</h1>
+      </main>
+    </Layout>
+  );
+}
+```
+
+### Customizing Header and Footer
+
+You can hide the header or footer:
+
+```tsx
+<Layout
+  siteData={siteData}
+  header={false}  // Hide header
+  footer={false}  // Hide footer
+>
+  <main>Landing page without navigation</main>
+</Layout>
+```
+
+### Choosing Header Variants
+
+Override the header variant from your code:
+
+```tsx
+<Layout
+  siteData={siteData}
+  headerVariant="centered"  // Options: classic, centered, transparent, floating, editorial
+>
+  <main>Content with centered header</main>
+</Layout>
+```
+
+### Fully Custom Headers
+
+Create your own header while using CMS navigation data:
+
+```tsx
+import { Layout, type HeaderData } from '@riverbankcms/sdk';
+
+function CustomHeader({ menu, logo, site }: HeaderData) {
+  return (
+    <header className="custom-header">
+      <a href="/">{logo?.url && <img src={logo.url} alt={site.title} />}</a>
+      <nav>
+        {menu.items.map(item => (
+          <a key={item.id} href={item.url.href}>{item.label}</a>
+        ))}
+      </nav>
+    </header>
+  );
+}
+
+export default async function MyPage() {
+  const siteData = await client.getSite({ slug: 'my-site' });
+
+  return (
+    <Layout
+      siteData={siteData}
+      header={(data) => <CustomHeader {...data} />}
+    >
+      <main>Custom header with CMS navigation</main>
+    </Layout>
+  );
+}
+```
+
+## Block Component
+
+The `Block` component renders individual CMS blocks. Use this when you want to mix CMS content with custom JSX, or render blocks outside of a full page context.
+
+### Basic Block Rendering
+
+```tsx
+import { Block } from '@riverbankcms/sdk';
+
+export default async function CustomPage() {
+  const siteData = await client.getSite({ slug: 'my-site' });
+
+  return (
+    <div>
+      <h1>Custom Header</h1>
+
+      {/* Render a CMS block inline */}
+      <Block
+        blockKind="block.hero"
+        content={{
+          headline: 'Welcome',
+          subheadline: 'To our custom page',
+          cta: { label: 'Get Started', href: '/signup' }
+        }}
+        theme={siteData.theme}
+        siteId={siteData.site.id}
+      />
+
+      <p>More custom content...</p>
+    </div>
+  );
+}
+```
+
+### Block with Data Loading
+
+Blocks can automatically load their data (e.g., blog posts, products) if they have data loaders configured:
+
+```tsx
+<Block
+  blockKind="block.blog-listing"
+  blockId="block-abc123"  // Block ID enables data loading
+  content={{ maxPosts: 10 }}
+  theme={siteData.theme}
+  siteId={siteData.site.id}
+  pageId={page.id}         // Optional: for context-aware loaders
+  client={client}          // Required for data loading
+/>
+```
+
+### Advanced Block Options
+
+```tsx
+<Block
+  blockKind="block.hero"
+  blockId="block-xyz"
+  content={{ heading: 'Welcome' }}
+  theme={theme}
+  siteId="site-123"
+
+  // Optional data loading context
+  pageId="page-456"
+  previewStage="preview"  // or "published"
+  client={client}
+
+  // Show placeholder data for missing loaders
+  usePlaceholders={true}
+/>
+```
+
+## Metadata Generation
+
+Generate SEO-optimized metadata for Next.js pages from Riverbank CMS data.
+
+### Basic Usage
+
+```tsx
+import { generatePageMetadata } from '@riverbankcms/sdk/metadata';
+import { loadPage } from '@riverbankcms/sdk';
+
+export async function generateMetadata({ params }) {
+  const pageData = await loadPage({ client, siteId, path: params.slug });
+  const siteData = await client.getSite({ id: siteId });
+
+  return generatePageMetadata({
+    page: pageData.page,
+    site: siteData.site,
+    path: params.slug || '/',
+    siteUrl: process.env.NEXT_PUBLIC_SITE_URL!,
+  });
+}
+```
+
+### With Custom Overrides
+
+```tsx
+const metadata = generatePageMetadata({
+  page: pageData.page,
+  site: siteData.site,
+  path: '/',
+  siteUrl: 'https://example.com',
+  overrides: {
+    title: 'Custom SEO Title',
+    description: 'Custom SEO description with keywords',
+    ogImage: 'https://example.com/og-image.jpg',
+    canonicalUrl: 'https://example.com/canonical-path',
+  },
+  googleSiteVerification: 'verification-token',
+});
+```
+
+### Preview Environment Metadata
+
+```tsx
+import { generatePreviewMetadata } from '@riverbankcms/sdk/metadata';
+
+// Adds noindex/nofollow for staging environments
+const metadata = generatePreviewMetadata({
+  page: pageData.page,
+  site: siteData.site,
+  path: '/',
+  siteUrl: 'https://preview.example.com',
+});
+```
+
+## Route Resolution
+
+Resolve URL paths to pages, redirects, or 404s for dynamic routing.
+
+### Single Route Resolution
+
+```tsx
+import { resolveRoute } from '@riverbankcms/sdk/routing';
+import { notFound, redirect } from 'next/navigation';
+
+export default async function DynamicPage({ params }) {
+  const path = `/${params.slug?.join('/') || ''}`;
+
+  const resolution = await resolveRoute({
+    client,
+    siteId: 'your-site-id',
+    path,
+  });
+
+  if (resolution.type === 'redirect') {
+    redirect(resolution.destination);
+  }
+
+  if (resolution.type === 'not-found') {
+    notFound();
+  }
+
+  return <Page {...resolution.pageData} />;
+}
+```
+
+### Batch Route Resolution
+
+```tsx
+import { resolveRoutes } from '@riverbankcms/sdk/routing';
+
+// Useful for sitemap generation or validation
+const resolutions = await resolveRoutes({
+  client,
+  siteId: 'your-site-id',
+  paths: ['/', '/about', '/services', '/contact'],
+});
+
+resolutions.forEach(({ path, resolution }) => {
+  if (resolution.type === 'page') {
+    console.log(`${path} → Page: ${resolution.pageData.page.name}`);
+  } else if (resolution.type === 'redirect') {
+    console.log(`${path} → Redirect to ${resolution.destination}`);
+  } else {
+    console.log(`${path} → Not found`);
+  }
+});
+```
+
+## Analytics
+
+Track page views, CTA clicks, form submissions, and custom events.
+
+### Add Analytics to Layout
+
+```tsx
+import { AnalyticsBootstrap } from '@riverbankcms/sdk/analytics';
+
+export default function RootLayout({ children }) {
+  return (
+    <html>
+      <body>
+        {children}
+
+        {/* Auto-tracks page views on navigation */}
+        <AnalyticsBootstrap
+          siteId="your-site-id"
+          siteSlug="your-site-slug"
+          endpoint="/api/analytics/collect"
+        />
+      </body>
+    </html>
+  );
+}
+```
+
+### Track Events in Components
+
+```tsx
+'use client';
+
+import { useAnalytics } from '@riverbankcms/sdk/analytics';
+
+export function MyComponent() {
+  const analytics = useAnalytics({
+    siteId: 'your-site-id',
+    siteSlug: 'your-site-slug',
+  });
+
+  const handleClick = () => {
+    analytics.trackCtaClick({ buttonLabel: 'Sign Up' });
+  };
+
+  const handleSubmit = () => {
+    analytics.trackFormSubmit({ formName: 'contact-form' });
+  };
+
+  const handleCustomEvent = () => {
+    analytics.trackEvent({
+      eventType: 'video_play',
+      metadata: { videoId: '123', duration: 120 },
+    });
+  };
+
+  return (
+    <>
+      <button onClick={handleClick}>Sign Up</button>
+      <form onSubmit={handleSubmit}>...</form>
+    </>
+  );
+}
+```
+
+## Theming
+
+Style Builder blocks to match your brand using the Theme Bridge. This provides CSS variables and optional component styles without requiring the full CMS theme system.
+
+### Quick Start
+
+Wrap your app with `ThemeBridgeProvider` and define your color tokens:
+
+```tsx
+import { ThemeBridgeProvider } from '@riverbankcms/sdk/theme-bridge';
+
+export default function RootLayout({ children }) {
+  return (
+    <ThemeBridgeProvider
+      config={{
+        tokens: {
+          primary: '#6d28d9',
+          secondary: '#4c1d95',
+          background: '#ffffff',
+          text: '#1e293b',
+        },
+      }}
+    >
+      {children}
+    </ThemeBridgeProvider>
+  );
+}
+```
+
+### Token System
+
+Define color tokens as key-value pairs. Keys become CSS variables (`--color-{key}`):
+
+```tsx
+<ThemeBridgeProvider
+  config={{
+    tokens: {
+      // Brand colors
+      primary: '#6d28d9',
+      secondary: '#4c1d95',
+
+      // Backgrounds
+      background: '#ffffff',
+      surface: '#f8fafc',
+
+      // Text
+      text: '#1e293b',
+      mutedText: '#64748b',
+
+      // UI
+      border: '#e2e8f0',
+      white: '#ffffff',
+
+      // Status
+      success: '#22c55e',
+      warning: '#f59e0b',
+      danger: '#ef4444',
+    },
+  }}
+>
+```
+
+Token values can be:
+- **Hex colors**: `'#6d28d9'` (converted to RGB for Tailwind alpha support)
+- **CSS variable refs**: `'var(--brand-purple)'` (passed through)
+- **RGB values**: `'109 40 217'` (used directly)
+
+### Design Presets
+
+Control typography, spacing, corners, and shadows:
+
+```tsx
+<ThemeBridgeProvider
+  config={{
+    tokens: { /* ... */ },
+
+    // Typography
+    typography: {
+      headingFamily: '"Inter", sans-serif',
+      bodyFamily: '"Inter", sans-serif',
+      headingWeight: 700,
+      bodyWeight: 400,
+    },
+
+    // Spacing density
+    spacing: 'standard',  // 'comfortable' | 'standard' | 'dense'
+
+    // Corner radius
+    corners: 'rounded',   // 'square' | 'soft' | 'rounded' | 'pill'
+
+    // Shadow intensity
+    shadows: 'medium',    // 'none' | 'low' | 'medium' | 'high'
+  }}
+>
+```
+
+### Component CSS (Opt-in)
+
+By default, only CSS variables are generated. Enable component CSS for buttons, cards, and inputs:
+
+```tsx
+<ThemeBridgeProvider
+  config={{
+    tokens: {
+      primary: '#6d28d9',
+      secondary: '#4c1d95',
+      white: '#ffffff',
+      surface: '#f8fafc',
+      text: '#1e293b',
+      border: '#e2e8f0',
+    },
+    corners: 'rounded',
+    shadows: 'medium',
+    components: {
+      buttons: true,  // Generates .button-primary, .button-secondary, etc.
+      cards: true,    // Generates .card-default, .card-elevated, etc.
+      inputs: true,   // Generates .form-input, .form-label, etc.
+    },
+  }}
+>
+```
+
+### Custom Component Variants
+
+Specify which variants to generate:
+
+```tsx
+components: {
+  buttons: {
+    variants: ['primary', 'secondary'],  // Only these variants
+  },
+  cards: {
+    variants: ['default', 'elevated'],
+  },
+}
+```
+
+### CSS Overrides
+
+Add custom CSS rules scoped to theme components:
+
+```tsx
+<ThemeBridgeProvider
+  config={{
+    tokens: { /* ... */ },
+    components: { buttons: true },
+    overrides: {
+      '.button-primary': 'border-radius: 9999px; font-weight: 700;',
+      '.button-primary:hover': 'transform: translateY(-2px);',
+    },
+  }}
+>
+```
+
+### Pass-Through to Design Systems
+
+Reference existing CSS variables from your design system:
+
+```tsx
+<ThemeBridgeProvider
+  config={{
+    tokens: {
+      primary: 'var(--brand-purple)',
+      secondary: 'var(--brand-navy)',
+      background: 'var(--ds-bg)',
+      text: 'var(--ds-text)',
+    },
+    components: { buttons: true },
+  }}
+>
+```
+
+### Using Generated CSS Directly
+
+For advanced use cases, generate CSS without the provider:
+
+```tsx
+import { generateThemeBridgeCss } from '@riverbankcms/sdk/theme-bridge';
+
+const { css, cssVars } = generateThemeBridgeCss({
+  tokens: {
+    primary: '#6d28d9',
+    background: '#ffffff',
+  },
+  components: { buttons: true },
+});
+
+// css: Full CSS string for injection
+// cssVars: Object of CSS variable name-value pairs
+```
+
+### Available Exports
+
+```tsx
+import {
+  // Provider component
+  ThemeBridgeProvider,
+  useThemeBridgeCss,
+
+  // CSS generator
+  generateThemeBridgeCss,
+
+  // Types
+  type ThemeBridgeConfig,
+  type ThemeBridgeTypography,
+  type ThemeBridgeSpacing,
+  type ThemeBridgeCorners,
+  type ThemeBridgeShadows,
+  type ThemeBridgeComponents,
+  type ThemeBridgeOutput,
+} from '@riverbankcms/sdk/theme-bridge';
+```
+
+## Block Field Options
+
+Customize field options for specific blocks directly in your SDK configuration. This allows SDK sites to define site-specific choices for select fields in system blocks.
+
+### Basic Configuration
+
+Add `blockFieldOptions` to your `riverbank.config.ts`:
+
+```typescript
+import { defineConfig } from '@riverbankcms/sdk/config';
+
+export default defineConfig({
+  siteId: 'your-site-id',
+  blockFieldOptions: {
+    'block.embed': {
+      layout: {
+        options: [
+          { value: 'showcase', label: 'Showcase Grid' },
+          { value: 'list', label: 'Simple List' },
+          { value: 'featured', label: 'Featured Hero' },
+        ]
+      }
+    }
+  }
+});
+```
+
+### How It Works
+
+1. **Block ID format**: Use `block.*` for system blocks or `custom.*` for custom blocks
+2. **Field ID**: The field within the block whose options you want to override
+3. **Options**: Array of `{ value, label }` objects that replace the default options
+
+When a block field uses the `sdkSelect` widget (like the embed block's `layout` field), it will:
+- Use SDK-provided options when available in `blockFieldOptions`
+- Fall back to the field's default options if no SDK options are configured
+
+### Types
+
+```typescript
+import type {
+  FieldSelectOption,
+  BlockFieldConfig,
+  BlockFieldOptionsMap,
+} from '@riverbankcms/sdk/config';
+
+// A single select option
+type FieldSelectOption = {
+  value: string;  // Value stored when selected
+  label: string;  // Display text in dropdown
+};
+
+// Configuration for a field
+type BlockFieldConfig = {
+  options?: FieldSelectOption[];  // Override select options
+};
+
+// Map of block IDs to field configurations
+type BlockFieldOptionsMap = Record<string, Record<string, BlockFieldConfig>>;
+```
+
+### Current Use Cases
+
+**Embed Block Layout**: The `block.embed` block uses `sdkSelect` for its `layout` field, allowing SDK sites to define custom layout options that match their site-specific renderers:
+
+```typescript
+export default defineConfig({
+  siteId: 'your-site-id',
+  blockFieldOptions: {
+    'block.embed': {
+      layout: {
+        options: [
+          { value: 'blog-grid', label: 'Blog Grid' },
+          { value: 'team-cards', label: 'Team Cards' },
+          { value: 'portfolio', label: 'Portfolio Gallery' },
+        ]
+      }
+    }
+  }
+});
+```
+
+Then in your block override, handle each layout:
+
+```tsx
+function EmbedRenderer({ content, data }) {
+  switch (content.layout) {
+    case 'blog-grid':
+      return <BlogGrid entries={data.entries} />;
+    case 'team-cards':
+      return <TeamCards entries={data.entries} />;
+    case 'portfolio':
+      return <PortfolioGallery entries={data.entries} />;
+    default:
+      return <DefaultList entries={data.entries} />;
+  }
+}
+```
+
+### Validation Rules
+
+- Block IDs must match pattern: `block.*` or `custom.*` (lowercase letters, numbers, hyphens)
+- Field IDs must be non-empty strings
+- Each option must have both `value` and `label` (non-empty strings)
+- At least one option is required when `options` is specified
+
+## Block Field Extensions
+
+Add custom fields to built-in block types without modifying the core CMS. This is different from `blockFieldOptions` (which overrides options for existing fields) – `blockFieldExtensions` lets you add entirely new fields.
+
+### Basic Configuration
+
+Add `blockFieldExtensions` to your `riverbank.config.ts`:
+
+```typescript
+import { defineConfig } from '@riverbankcms/sdk/config';
+
+export default defineConfig({
+  siteId: 'your-site-id',
+  blockFieldExtensions: {
+    'block.body-text': {
+      fields: [
+        {
+          id: 'layout',
+          type: 'select',
+          label: 'Layout',
+          defaultValue: 'default',
+          required: false,
+          multiple: false,
+          options: [
+            { value: 'default', label: 'Default' },
+            { value: 'wide', label: 'Wide' },
+            { value: 'narrow', label: 'Narrow' },
+            { value: 'pullquote', label: 'Pull Quote' },
+          ],
+        },
+      ],
+    },
+    'block.hero': {
+      fields: [
+        {
+          id: 'videoBackground',
+          type: 'media',
+          label: 'Video Background',
+          description: 'Optional video to play behind the hero',
+          mediaKinds: ['video'],
+          required: false,
+        },
+        {
+          id: 'overlayOpacity',
+          type: 'number',
+          label: 'Overlay Opacity',
+          description: 'Darkness of the overlay (0-100)',
+          defaultValue: 50,
+          required: false,
+        },
+      ],
+    },
+  },
+});
+```
+
+### How It Works
+
+1. **Extended fields appear at the end** of the block's editing form in the CMS
+2. **Field values are stored** alongside normal block content
+3. **Values are accessible** in your `blockOverrides` via the `content` prop
+4. **All field types supported**: text, select, media, repeater, group, etc.
+
+### Accessing Extended Fields in blockOverrides
+
+```tsx
+import { loadPage, Page } from '@riverbankcms/sdk';
+
+export default async function CMSPage({ params }) {
+  const pageData = await loadPage({ client, siteId, path: '/' });
+
+  return (
+    <Page
+      {...pageData}
+      blockOverrides={{
+        bodyText: ({ content }) => {
+          // Extended field values are available on content
+          const layout = content.layout ?? 'default';
+
+          const layoutClass = {
+            default: 'max-w-prose mx-auto',
+            wide: 'max-w-4xl mx-auto',
+            narrow: 'max-w-md mx-auto',
+            pullquote: 'max-w-lg mx-auto text-xl italic border-l-4 pl-6',
+          }[layout];
+
+          return (
+            <div className={layoutClass}>
+              <RichText content={content.body} />
+            </div>
+          );
+        },
+        hero: ({ content }) => {
+          const { videoBackground, overlayOpacity = 50 } = content;
+
+          return (
+            <div className="relative">
+              {videoBackground && (
+                <video
+                  src={videoBackground.url}
+                  className="absolute inset-0 w-full h-full object-cover"
+                  autoPlay
+                  muted
+                  loop
+                />
+              )}
+              <div
+                className="absolute inset-0 bg-black"
+                style={{ opacity: overlayOpacity / 100 }}
+              />
+              <div className="relative z-10">
+                <h1>{content.headline}</h1>
+              </div>
+            </div>
+          );
+        },
+      }}
+    />
+  );
+}
+```
+
+### Types
+
+```typescript
+import type {
+  BlockFieldExtension,
+  BlockFieldExtensionsMap,
+  FieldDefinition,
+} from '@riverbankcms/sdk/config';
+
+// Configuration for extending a single block
+type BlockFieldExtension = {
+  fields: FieldDefinition[];  // Same field format as block manifests
+};
+
+// Map of block IDs to their extensions
+type BlockFieldExtensionsMap = Record<string, BlockFieldExtension>;
+```
+
+### Validation Rules
+
+- **Block IDs must be system blocks**: Only `block.*` format (e.g., `block.body-text`, `block.hero`). Custom blocks (`custom.*`) should define their fields directly in `customBlocks`.
+- **Field IDs must be unique**: Extended field IDs cannot conflict with existing fields in the block. The CLI will error if you try to add a field with an ID that already exists.
+- **Required fields need defaultValue**: If `required: true`, you must provide a `defaultValue`. This ensures existing blocks (created before the extension) can still be edited.
+- **At least one field required**: Each block extension must have at least one field.
+
+### Use Cases
+
+**Layout variations for text blocks:**
+```typescript
+'block.body-text': {
+  fields: [
+    {
+      id: 'layout',
+      type: 'select',
+      label: 'Layout',
+      defaultValue: 'default',
+      required: false,
+      multiple: false,
+      options: [
+        { value: 'default', label: 'Default' },
+        { value: 'wide', label: 'Wide' },
+        { value: 'sidebar', label: 'With Sidebar' },
+      ],
+    },
+  ],
+}
+```
+
+**Custom styling options:**
+```typescript
+'block.hero': {
+  fields: [
+    {
+      id: 'textAlignment',
+      type: 'select',
+      label: 'Text Alignment',
+      defaultValue: 'center',
+      required: false,
+      multiple: false,
+      options: [
+        { value: 'left', label: 'Left' },
+        { value: 'center', label: 'Center' },
+        { value: 'right', label: 'Right' },
+      ],
+    },
+    {
+      id: 'showBreadcrumbs',
+      type: 'boolean',
+      label: 'Show Breadcrumbs',
+      defaultValue: false,
+      required: false,
+    },
+  ],
+}
+```
+
+**Adding metadata fields:**
+```typescript
+'block.blog-listing': {
+  fields: [
+    {
+      id: 'analyticsId',
+      type: 'text',
+      label: 'Analytics ID',
+      description: 'Track this specific listing in analytics',
+      required: false,
+      multiline: false,
+    },
+  ],
+}
+```
+
+### Comparison: blockFieldOptions vs blockFieldExtensions
+
+| Feature | `blockFieldOptions` | `blockFieldExtensions` |
+|---------|---------------------|------------------------|
+| Purpose | Override options for existing select fields | Add new fields to blocks |
+| Supports | Select field options only | All field types |
+| Use case | Customize dropdown choices | Add new data fields |
+| Block types | System and custom blocks | System blocks only |
+
+Use **both together** for maximum customization:
+
+```typescript
+export default defineConfig({
+  siteId: 'your-site-id',
+
+  // Override options for existing fields
+  blockFieldOptions: {
+    'block.embed': {
+      layout: {
+        options: [
+          { value: 'blog-grid', label: 'Blog Grid' },
+          { value: 'team-cards', label: 'Team Cards' },
+        ],
+      },
+    },
+  },
+
+  // Add new fields to blocks
+  blockFieldExtensions: {
+    'block.body-text': {
+      fields: [
+        {
+          id: 'layout',
+          type: 'select',
+          label: 'Layout',
+          defaultValue: 'default',
+          required: false,
+          multiple: false,
+          options: [
+            { value: 'default', label: 'Default' },
+            { value: 'wide', label: 'Wide' },
+          ],
+        },
+      ],
+    },
+  },
+});
+```
+
+## Custom Blocks
+
+Define site-specific blocks directly in your SDK configuration. Custom blocks appear in the CMS block picker alongside system blocks, are edited using CMS-generated forms, and are rendered by your own React components.
+
+### Quick Start
+
+1. **Define the block schema** in your `riverbank.config.ts`:
+
+```typescript
+import { defineConfig } from '@riverbankcms/sdk/config';
+
+export default defineConfig({
+  siteId: 'your-site-id',
+  customBlocks: [
+    {
+      id: 'custom.team-member',
+      title: 'Team Member',
+      titleSource: 'name',
+      description: 'Display a team member with photo and bio',
+      category: 'content',
+      icon: 'User',
+      tags: ['team', 'about'],
+      fields: [
+        { id: 'name', type: 'text', label: 'Name', required: true, multiline: false },
+        { id: 'role', type: 'text', label: 'Role', required: false, multiline: false },
+        { id: 'photo', type: 'media', label: 'Photo', required: false, mediaKinds: ['image'] },
+        { id: 'bio', type: 'richText', label: 'Bio', required: false },
+      ],
+    },
+  ],
+});
+```
+
+2. **Create your component** to render the block:
+
+```tsx
+// components/blocks/TeamMember.tsx
+import type { SystemBlockComponentProps } from '@riverbankcms/blocks';
+
+type TeamMemberContent = {
+  name: string;
+  role?: string;
+  photo?: { url: string; alt?: string };
+  bio?: string;
+};
+
+export function TeamMember({ content }: SystemBlockComponentProps<TeamMemberContent>) {
+  return (
+    <div className="flex items-start gap-6 p-6">
+      {content.photo && (
+        <img
+          src={content.photo.url}
+          alt={content.photo.alt || content.name}
+          className="h-24 w-24 rounded-full object-cover"
+        />
+      )}
+      <div>
+        <h3 className="text-xl font-bold">{content.name}</h3>
+        {content.role && <p className="text-gray-600">{content.role}</p>}
+        {content.bio && (
+          <div className="mt-2 prose" dangerouslySetInnerHTML={{ __html: content.bio }} />
+        )}
+      </div>
+    </div>
+  );
+}
+```
+
+3. **Register the component** with `blockOverrides`:
+
+```tsx
+// app/[...slug]/page.tsx
+import { loadPage, Page } from '@riverbankcms/sdk';
+import { TeamMember } from '@/components/blocks/TeamMember';
+
+export default async function CMSPage({ params }) {
+  const pageData = await loadPage({
+    client,
+    siteId: process.env.SITE_ID!,
+    path: `/${params.slug?.join('/') || ''}`,
+  });
+
+  return (
+    <Page
+      {...pageData}
+      blockOverrides={{
+        'custom.team-member': TeamMember,
+      }}
+    />
+  );
+}
+```
+
+### Block Definition Schema
+
+| Property | Type | Required | Description |
+|----------|------|----------|-------------|
+| `id` | `custom.${string}` | Yes | Unique block ID, must start with `custom.` |
+| `title` | `string` | Yes | Display name in block picker |
+| `titleSource` | `string` | No | Field ID to use as block title in lists |
+| `description` | `string` | No | Description shown in block picker |
+| `category` | `BlockCategory` | Yes | One of: `marketing`, `content`, `blog`, `media`, `layout`, `interactive` |
+| `icon` | `string` | No | Lucide icon name (e.g., `User`, `CreditCard`) |
+| `tags` | `string[]` | No | Search tags for discoverability |
+| `fields` | `FieldDefinition[]` | Yes | Field definitions for the block |
+
+### Supported Field Types
+
+All field types from the CMS are supported:
+
+**Basic Types:**
+- `text` - Single or multiline text
+- `richText` - Rich text editor with formatting
+- `number` - Numeric input
+- `boolean` - Toggle/checkbox
+
+**Media & Links:**
+- `media` - Image, video, or file upload
+- `url` - URL input with validation
+- `link` - Internal or external link picker
+
+**Selection:**
+- `select` - Dropdown selection
+- `reference` - Reference to other content entries
+
+**Date/Time:**
+- `date` - Date picker
+- `time` - Time picker
+- `datetime` - Combined date and time
+
+**Complex Types:**
+- `group` - Group related fields together
+- `repeater` - Repeatable list of items
+- `modal` - Fields in a modal dialog
+- `tabGroup` - Tabbed field groups
+
+### Examples
+
+**Pricing Card:**
+
+```typescript
+{
+  id: 'custom.pricing-card',
+  title: 'Pricing Card',
+  titleSource: 'planName',
+  category: 'marketing',
+  icon: 'CreditCard',
+  fields: [
+    { id: 'planName', type: 'text', label: 'Plan Name', required: true, multiline: false },
+    { id: 'price', type: 'text', label: 'Price', required: false, multiline: false, description: 'e.g., "$29/mo"' },
+    { id: 'featured', type: 'boolean', label: 'Featured Plan', required: false },
+    {
+      id: 'features',
+      type: 'repeater',
+      label: 'Features',
+      required: false,
+      itemLabel: 'Feature',
+      maxItems: 10,
+      fields: [
+        { id: 'text', type: 'text', label: 'Feature', required: true, multiline: false },
+        { id: 'included', type: 'boolean', label: 'Included', required: false },
+      ],
+    },
+    { id: 'ctaLabel', type: 'text', label: 'Button Label', required: false, multiline: false },
+    { id: 'ctaLink', type: 'link', label: 'Button Link', required: false },
+  ],
+}
+```
+
+**Testimonial:**
+
+```typescript
+{
+  id: 'custom.testimonial',
+  title: 'Testimonial',
+  titleSource: 'authorName',
+  category: 'content',
+  icon: 'Quote',
+  fields: [
+    { id: 'quote', type: 'richText', label: 'Quote', required: true },
+    { id: 'authorName', type: 'text', label: 'Author Name', required: true, multiline: false },
+    { id: 'authorTitle', type: 'text', label: 'Author Title', required: false, multiline: false },
+    { id: 'authorPhoto', type: 'media', label: 'Author Photo', required: false, mediaKinds: ['image'] },
+    { id: 'companyLogo', type: 'media', label: 'Company Logo', required: false, mediaKinds: ['image'] },
+    { id: 'rating', type: 'number', label: 'Rating (1-5)', required: false },
+  ],
+}
+```
+
+### Validation Rules
+
+- Maximum 20 custom blocks per site
+- Block IDs must be unique within the site
+- Block IDs must start with `custom.` followed by lowercase letters, numbers, or hyphens
+- `titleSource` must reference a valid field ID if provided
+- At least one field is required per block
+- Maximum 5 data loaders per block
+
+### Best Practices
+
+1. **Use descriptive IDs**: `custom.team-member` is better than `custom.tm`
+2. **Set `titleSource`**: Helps editors identify blocks in the page structure
+3. **Add descriptions**: Help editors understand when to use each block
+4. **Group related fields**: Use `group` for related fields that should appear together
+5. **Validate required fields**: Mark essential fields as `required: true`
+6. **Provide defaults**: Use `defaultValue` for optional fields with sensible defaults
+
+## Custom Block Data Loaders
+
+Custom blocks can fetch data automatically using data loaders. There are two approaches:
+
+1. **Config-based loaders** - Declarative loaders defined in `riverbank.config.ts` for whitelisted CMS endpoints
+2. **Code-based loaders** - Functions passed to `loadPage()` for external APIs
+
+Both loader types run server-side during `loadPage()`. Data is passed to your component via the `data` prop.
+
+### Config-Based Loaders (CMS Endpoints)
+
+Define loaders declaratively in your block definition. These are restricted to whitelisted CMS endpoints for security.
+
+**Supported Endpoints:**
+
+| Endpoint | Description |
+|----------|-------------|
+| `listPublishedEntries` | Fetch published content entries |
+| `getPublishedEntryPreview` | Fetch a single entry by slug |
+| `listPublicEvents` | Fetch events |
+| `getPublicFormById` | Fetch form configuration |
+| `getPublicBookingServices` | Fetch booking services |
+
+**Parameter Bindings:**
+
+Loader params can be static values or dynamic bindings:
+
+- `{ $bind: { from: 'content.fieldName' } }` - Bind to a block field value
+- `{ $bind: { from: 'content.fieldName', fallback: '10' } }` - With fallback
+- `{ $bind: { from: '$root.siteId' } }` - Bind to site ID from page context
+- `{ $bind: { from: '$root.pageId' } }` - Bind to page ID
+- `{ $bind: { from: '$root.previewStage' } }` - 'published' or 'preview'
+
+**Example: Blog Listing Block**
+
+```typescript
+// riverbank.config.ts
+import { defineConfig } from '@riverbankcms/sdk/config';
+
+export default defineConfig({
+  siteId: 'your-site-id',
+  customBlocks: [
+    {
+      id: 'custom.featured-posts',
+      title: 'Featured Posts',
+      category: 'blog',
+      icon: 'FileText',
+      fields: [
+        { id: 'limit', type: 'number', label: 'Number of posts', required: false },
+        { id: 'category', type: 'text', label: 'Category filter', required: false, multiline: false },
+      ],
+      dataLoaders: {
+        posts: {
+          endpoint: 'listPublishedEntries',
+          params: {
+            siteId: { $bind: { from: '$root.siteId' } },
+            type: 'blog-post',
+            limit: { $bind: { from: 'content.limit', fallback: '10' } },
+          },
+        },
+      },
+    },
+  ],
+});
+```
+
+```tsx
+// components/blocks/FeaturedPosts.tsx
+import type { SystemBlockComponentProps } from '@riverbankcms/blocks';
+
+type FeaturedPostsContent = {
+  limit?: number;
+  category?: string;
+};
+
+type FeaturedPostsData = {
+  posts: { entries: Array<{ id: string; title: string; slug: string }> };
+};
+
+export function FeaturedPosts({
+  content,
+  data,
+}: SystemBlockComponentProps<FeaturedPostsContent, FeaturedPostsData>) {
+  const posts = data?.posts?.entries ?? [];
+
+  return (
+    <div className="grid gap-4">
+      {posts.map((post) => (
+        <article key={post.id}>
+          <a href={`/blog/${post.slug}`}>
+            <h3>{post.title}</h3>
+          </a>
+        </article>
+      ))}
+    </div>
+  );
+}
+```
+
+### Code-Based Loaders (External APIs)
+
+For data from external APIs, pass loader functions to `loadPage()`. This gives you full control over the fetch logic.
+
+**Example: E-commerce Product Block**
+
+```typescript
+// app/[...slug]/page.tsx
+import { loadPage, Page } from '@riverbankcms/sdk';
+import { FeaturedProducts } from '@/components/blocks/FeaturedProducts';
+
+export default async function CMSPage({ params }) {
+  const pageData = await loadPage({
+    client,
+    siteId: process.env.SITE_ID!,
+    path: `/${params.slug?.join('/') || ''}`,
+    dataLoaderOverrides: {
+      'custom.featured-products': {
+        products: async (ctx) => {
+          // Access block content for parameters
+          const categoryId = ctx.content.categoryId as string;
+          const limit = (ctx.content.limit as number) ?? 10;
+
+          const res = await fetch(
+            `https://api.shop.com/products?category=${categoryId}&limit=${limit}`,
+            { headers: { 'Authorization': `Bearer ${process.env.SHOP_API_KEY}` } }
+          );
+
+          return res.json();
+        },
+      },
+    },
+  });
+
+  return (
+    <Page
+      {...pageData}
+      blockOverrides={{
+        'custom.featured-products': FeaturedProducts,
+      }}
+    />
+  );
+}
+```
+
+```tsx
+// components/blocks/FeaturedProducts.tsx
+import type { SystemBlockComponentProps } from '@riverbankcms/blocks';
+
+type ProductsContent = {
+  categoryId: string;
+  limit?: number;
+};
+
+type ProductsData = {
+  products: Array<{ id: string; name: string; price: number; image: string }>;
+};
+
+export function FeaturedProducts({
+  content,
+  data,
+}: SystemBlockComponentProps<ProductsContent, ProductsData>) {
+  const products = data?.products ?? [];
+
+  return (
+    <div className="grid grid-cols-3 gap-6">
+      {products.map((product) => (
+        <div key={product.id} className="border rounded p-4">
+          <img src={product.image} alt={product.name} />
+          <h3>{product.name}</h3>
+          <p>${product.price}</p>
+        </div>
+      ))}
+    </div>
+  );
+}
+```
+
+### DataLoaderContext
+
+Code-based loaders receive context about the block and page:
+
+```typescript
+interface DataLoaderContext {
+  /** Site ID from page context */
+  siteId: string;
+
+  /** Page ID from page context */
+  pageId: string;
+
+  /** Unique block instance ID */
+  blockId: string;
+
+  /** Block kind (e.g., 'custom.featured-products') */
+  blockKind: string;
+
+  /** The block's CMS content (field values) */
+  content: Record<string, unknown>;
+
+  /** Whether fetching preview/draft content */
+  previewStage: 'published' | 'preview';
+}
+```
+
+### Combining Config and Code Loaders
+
+You can use both loader types together. Config loaders run first, then code loaders. On key conflicts, code loaders take precedence.
+
+```typescript
+// riverbank.config.ts - Config loader for CMS data
+customBlocks: [{
+  id: 'custom.product-showcase',
+  dataLoaders: {
+    relatedPosts: {
+      endpoint: 'listPublishedEntries',
+      params: {
+        siteId: { $bind: { from: '$root.siteId' } },
+        type: 'blog-post',
+        limit: '3',
+      },
+    },
+  },
+}]
+
+// page.tsx - Code loader for external API
+const pageData = await loadPage({
+  client,
+  siteId,
+  path: '/',
+  dataLoaderOverrides: {
+    'custom.product-showcase': {
+      products: async (ctx) => fetchProductsFromShopify(ctx.content.collectionId),
+    },
+  },
+});
+
+// Component receives both: data.relatedPosts (CMS) and data.products (Shopify)
+```
+
+### Error Handling
+
+Data loaders are best-effort. If a loader fails:
+
+- The error is logged to console
+- The loader key is undefined in the `data` prop
+- Other loaders continue executing
+- Your component should handle missing data gracefully
+
+```tsx
+function MyBlock({ data }: SystemBlockComponentProps<Content, Data>) {
+  // Handle missing data
+  const products = data?.products ?? [];
+
+  if (products.length === 0) {
+    return <p>No products available</p>;
+  }
+
+  return <ProductGrid products={products} />;
+}
+```
+
+### Data Exports
+
+Import data utilities from `@riverbankcms/sdk/data`:
+
+```typescript
+import {
+  // Core prefetch function
+  prefetchBlockData,
+
+  // Code loader execution
+  executeCodeLoaders,
+  mergeLoaderResults,
+
+  // Types
+  type DataLoaderContext,
+  type DataLoaderFn,
+  type BlockLoaderMap,
+  type DataLoaderOverrides,
+  type PrefetchContext,
+  type ResolvedBlockData,
+  type SdkPrefetchOptions,
+} from '@riverbankcms/sdk/data';
+```
+
+## Additional Exports
+
+- `@riverbankcms/sdk/rendering` - Low-level rendering components
+- `@riverbankcms/sdk/theme` - Theme utilities
+- `@riverbankcms/sdk/theme-bridge` - Simplified theming for SDK sites
+- `@riverbankcms/sdk/hooks` - (Deprecated: use `/client` instead)
+- `@riverbankcms/sdk/data` - Data prefetching utilities
+- `@riverbankcms/sdk/metadata` - Metadata generation helpers
+- `@riverbankcms/sdk/routing` - Route resolution helpers
+- `@riverbankcms/sdk/analytics` - Analytics tracking helpers
+- `@riverbankcms/sdk/config` - Site configuration utilities (includes `defineConfig`, `RiverbankSiteConfig`, `BlockFieldOptionsMap`, `FieldSelectOption`, etc.)