@riverbankcms/sdk 0.70.2 → 0.70.3

package/README.md

@@ -3257,6 +3257,35 @@ export default Page;
 export { generateMetadata };
 ```
 
+### Lazy Block Overrides
+
+Eager `blockOverrides` remain supported and are a good fit for small server-safe components. For client-heavy or rarely used custom blocks, register a lazy override so `createCatchAllPage()` resolves only the override modules needed by the page or entry template being rendered:
+
+```tsx
+// src/app/[[...slug]]/page.tsx
+import { createCatchAllPage } from '@riverbankcms/sdk/next';
+import { defineLazyBlockOverride } from '@riverbankcms/sdk/rendering';
+import { getRiverbankClient } from '@/lib/builder-client';
+import config from '@/riverbank.config';
+
+const { Page, generateMetadata } = createCatchAllPage({
+  getClient: getRiverbankClient,
+  config,
+  blockOverrides: {
+    'custom.quiz': defineLazyBlockOverride(async () =>
+      import('@/components/blocks/QuizBlock').then((module) => module.QuizBlock)
+    ),
+  },
+});
+
+export default Page;
+export { generateMetadata };
+```
+
+Keep the `import()` inside the lazy factory. Wrapping a component that was imported at the top of the route file is still eager from the bundler's point of view and will not slim the catch-all route graph. Lazy factories must be wrapped with `defineLazyBlockOverride()`; raw promise-returning functions are not treated as lazy overrides.
+
+`createCatchAllPage()` filters and resolves lazy overrides per rendered page, so unused factories are not invoked. Next.js still builds the client-reference manifest from the static catch-all route graph, though, so a static `import('./HeavyClientBlock')` inside the route graph can still appear in internal build manifests even when that block is not on the current page. For client-heavy blocks, keep the server override wrapper small and put ALTCHA/forms/booking widgets behind block-local client boundaries, then verify the production build artifacts for the specific site.
+
 This single call replaces ~160 lines of typical boilerplate that handles:
 - Path resolution from URL slugs
 - Content loading (pages and entries)

package/dist/_dts/sdk/src/cli/commands/delete.d.ts

@@ -6,6 +6,9 @@
  * Usage:
  *   riverbankcms delete entry <type> <identifier>
  *   riverbankcms delete block <page-identifier> <block-identifier>
+ *
+ * These destructive one-off commands intentionally remain direct for #931 so
+ * their confirmation and remote --yes safety semantics stay unchanged.
  */
 import { Command } from 'commander';
 export declare const deleteCommand: Command;

package/dist/_dts/sdk/src/cli/commands/style.d.ts

@@ -4,6 +4,7 @@
  * Apply bounded site-style selections via the command-backed theme API.
  */
 import { Command } from 'commander';
+import { type CuratedSiteStyle } from '../../../../theme-core/src/site-styles/index';
 import type { ThemeStyleSelectionApplyInput } from '../../client/management';
 export type StyleApplyOptions = Readonly<{
     siteStyleId: string;
@@ -15,5 +16,22 @@ export type StyleApplyOptions = Readonly<{
     headerLookId?: string;
     footerLookId?: string;
 }>;
+export type StyleCatalogListOptions = Readonly<{
+    siteStyleId?: string;
+}>;
+export type StyleCatalogChoice = Readonly<{
+    id: string;
+    label: string;
+}>;
+export type StyleCatalogListRow = Readonly<{
+    siteStyleId: string;
+    name: string;
+    palettes: readonly StyleCatalogChoice[];
+    buttonPersonalities: readonly StyleCatalogChoice[];
+    headerLooks: readonly StyleCatalogChoice[];
+    footerLooks: readonly StyleCatalogChoice[];
+}>;
 export declare function buildStyleSelectionApplyInputFromOptions(options: StyleApplyOptions): ThemeStyleSelectionApplyInput;
+export declare function buildStyleCatalogListRows(styles?: readonly CuratedSiteStyle[], options?: StyleCatalogListOptions): readonly StyleCatalogListRow[];
+export declare function formatStyleCatalogListRow(row: StyleCatalogListRow): string[];
 export declare const styleCommand: Command;

package/dist/_dts/sdk/src/cli/helpers.d.ts

@@ -5,6 +5,7 @@
  * Reduces duplication and ensures consistent behavior.
  */
 import { Command } from 'commander';
+import type { SiteId } from '../../../core/src/index';
 import type { ManagementClient } from '../client/management/types';
 import { type OutputContext } from './output';
 import { type CliErrorContext } from './errors';
@@ -52,6 +53,8 @@ export interface CommandContext {
     client: ManagementClient;
     isRemote: boolean;
     isJsonOutput: boolean;
+    targetEnv: EnvTarget;
+    siteId: SiteId;
     /** Environment targets for this operation */
     envTargets: EnvTarget[];
 }
@@ -271,6 +274,11 @@ export declare function handleCommandError(error: unknown, output: OutputContext
  * }))
  */
 export declare function withErrorHandling<TArgs extends unknown[]>(action: (...args: [...TArgs, Command]) => Promise<void>): (...args: [...TArgs, Command]) => Promise<void>;
+/**
+ * Wrap a command action so handlers receive a resolved command context instead
+ * of the raw Commander instance.
+ */
+export declare function withCommandContext<TArgs extends unknown[], TOptions = unknown>(action: (ctx: CommandContext, ...args: [...TArgs, TOptions]) => Promise<void>): (...args: [...TArgs, TOptions, Command]) => Promise<void>;
 /**
  * Wrap a destructive command action with confirmation prompt and error handling.
  *
@@ -289,39 +297,6 @@ export declare function withErrorHandling<TArgs extends unknown[]>(action: (...a
  * ))
  */
 export declare function withConfirmation<TArgs extends unknown[]>(getMessage: (...args: TArgs) => string, action: (ctx: CommandContext, ...args: TArgs) => Promise<void>): (...args: [...TArgs, ConfirmOptions, Command]) => Promise<void>;
-/**
- * Configuration for publish/unpublish command factories.
- */
-export interface PublishCommandConfig {
-    /** Resource name for display (e.g., 'entry', 'page') */
-    resourceName: string;
-    /** Argument names (e.g., ['type', 'identifier'] or ['identifier']) */
-    args: readonly string[];
-    /** Function to call the appropriate client method */
-    action: (client: ManagementClient, ...args: string[]) => Promise<void>;
-}
-/**
- * Create a publish command for a resource.
- *
- * @example
- * const publishCommand = createPublishCommand({
- *   resourceName: 'entry',
- *   args: ['type', 'identifier'],
- *   action: (client, type, id) => client.entries.publish(type, id),
- * });
- */
-export declare function createPublishCommand(config: PublishCommandConfig): Command;
-/**
- * Create an unpublish command for a resource.
- *
- * @example
- * const unpublishCommand = createUnpublishCommand({
- *   resourceName: 'entry',
- *   args: ['type', 'identifier'],
- *   action: (client, type, id) => client.entries.unpublish(type, id),
- * });
- */
-export declare function createUnpublishCommand(config: PublishCommandConfig): Command;
 /**
  * Configuration for get command factory.
  */

package/dist/_dts/sdk/src/cli/site-commands/oneOffCommands.d.ts

@@ -0,0 +1,81 @@
+import { type Result, type SiteId } from '../../../../core/src/index';
+import type { ManagementBlock, ManagementClient, ManagementEntry, ManagementNavigationMenu, ManagementPage, NavigationItemInput } from '../../client/management/types';
+import type { EnvTarget } from '../helpers';
+import { type CliCommandCompileBatchSuccessWithReports, type CliCommandValidationCompileError } from './commandRuntime';
+import { type EntryCommandReportSubject, type EntrySiteCommand, type EntrySiteCommandType } from './entryCommands';
+import { type NavigationCommandReportSubject, type NavigationSiteCommand, type NavigationSiteCommandType } from './navigationCommands';
+import { type PageCommandReportSubject, type PageSiteCommand, type PageSiteCommandType } from './pageCommands';
+export type OneOffCommandBatchSource = 'one_off_entry' | 'one_off_page' | 'one_off_block' | 'one_off_navigation';
+type OneOffCompileInput<TMutation> = Readonly<{
+    source: OneOffCommandBatchSource;
+    siteId: SiteId;
+    targetEnv: EnvTarget;
+    mutation: TMutation;
+}>;
+export type OneOffEntryMutation = Readonly<{
+    kind: 'upsert';
+    contentType: string;
+    identifier: string;
+    data: Record<string, unknown>;
+    slug?: string;
+}> | Readonly<{
+    kind: 'publish' | 'unpublish';
+    contentType: string;
+    identifier: string;
+}>;
+export type OneOffPageMutation = Readonly<{
+    kind: 'upsert';
+    identifier: string;
+    title: string;
+    path: string;
+    seoTitle?: string;
+    seoDescription?: string;
+}> | Readonly<{
+    kind: 'publish' | 'unpublish';
+    identifier: string;
+}>;
+export type OneOffBlockMutation = Readonly<{
+    kind: 'upsert';
+    pageIdentifier: string;
+    blockIdentifier: string;
+    blockKind: string;
+    data: Record<string, unknown>;
+}> | Readonly<{
+    kind: 'reorder';
+    pageIdentifier: string;
+    blockIdentifiers: readonly string[];
+}>;
+export type OneOffNavigationMutation = Readonly<{
+    kind: 'upsert';
+    menuName: string;
+    items: readonly NavigationItemInput[];
+}>;
+export type OneOffEntryCommandCompileSuccess = CliCommandCompileBatchSuccessWithReports<EntrySiteCommandType, EntryCommandReportSubject>;
+export type OneOffPageCommandCompileSuccess = CliCommandCompileBatchSuccessWithReports<PageSiteCommandType, PageCommandReportSubject>;
+export type OneOffNavigationCommandCompileSuccess = CliCommandCompileBatchSuccessWithReports<NavigationSiteCommandType, NavigationCommandReportSubject>;
+export declare function compileOneOffEntryCommand(input: OneOffCompileInput<OneOffEntryMutation>): Result<OneOffEntryCommandCompileSuccess, CliCommandValidationCompileError>;
+export declare function compileOneOffPageCommand(input: OneOffCompileInput<OneOffPageMutation>): Result<OneOffPageCommandCompileSuccess, CliCommandValidationCompileError>;
+export declare function compileOneOffBlockCommand(input: OneOffCompileInput<OneOffBlockMutation>): Result<OneOffPageCommandCompileSuccess, CliCommandValidationCompileError>;
+export declare function compileOneOffNavigationCommand(input: OneOffCompileInput<OneOffNavigationMutation>): Result<OneOffNavigationCommandCompileSuccess, CliCommandValidationCompileError>;
+export declare function executeOneOffEntryCommand<TResult>(input: Readonly<{
+    compiledPlan: Pick<OneOffEntryCommandCompileSuccess, 'plan'>;
+    client: Pick<ManagementClient, 'entries'>;
+    apply: (command: EntrySiteCommand, client: Pick<ManagementClient, 'entries'>) => Promise<TResult>;
+}>): Promise<TResult>;
+export declare function executeOneOffPageCommand<TResult>(input: Readonly<{
+    compiledPlan: Pick<OneOffPageCommandCompileSuccess, 'plan'>;
+    client: Pick<ManagementClient, 'pages' | 'blocks'>;
+    apply: (command: PageSiteCommand, client: Pick<ManagementClient, 'pages' | 'blocks'>) => Promise<TResult>;
+}>): Promise<TResult>;
+export declare function executeOneOffNavigationCommand<TResult>(input: Readonly<{
+    compiledPlan: Pick<OneOffNavigationCommandCompileSuccess, 'plan'>;
+    client: Pick<ManagementClient, 'navigation'>;
+    apply: (command: NavigationSiteCommand, client: Pick<ManagementClient, 'navigation'>) => Promise<TResult>;
+}>): Promise<TResult>;
+export declare function applyOneOffEntryCommand(command: EntrySiteCommand, client: Pick<ManagementClient, 'entries'>): Promise<ManagementEntry | void>;
+export declare function applyOneOffEntryCommandReturningEntry(command: EntrySiteCommand, client: Pick<ManagementClient, 'entries'>): Promise<ManagementEntry>;
+export declare function applyOneOffPageCommand(command: PageSiteCommand, client: Pick<ManagementClient, 'pages' | 'blocks'>): Promise<ManagementPage | ManagementBlock | void>;
+export declare function applyOneOffPageCommandReturningPage(command: PageSiteCommand, client: Pick<ManagementClient, 'pages' | 'blocks'>): Promise<ManagementPage>;
+export declare function applyOneOffPageCommandReturningBlock(command: PageSiteCommand, client: Pick<ManagementClient, 'pages' | 'blocks'>): Promise<ManagementBlock>;
+export declare function applyOneOffNavigationCommand(command: NavigationSiteCommand, client: Pick<ManagementClient, 'navigation'>): Promise<ManagementNavigationMenu>;
+export {};

package/dist/_dts/sdk/src/components.d.ts

@@ -27,4 +27,5 @@ export { Layout } from './rendering/components/Layout';
 export type { LayoutProps, HeaderData, FooterData } from './rendering/components/Layout';
 export { PageRenderer, ThemeScope, buildThemeRuntime, RichText, resolveImageUrl, resolveImageUrlWithContext, resolveImageSourceSetWithContext, ImagePresets, } from './rendering';
 export type { AppointmentBookingContent, BlogListingContent, BlogPostContent, BodyTextAlignment, BodyTextContent, CollectionContent, ColumnsContent, CourseDetailsContent, CourseRegistrationContent, CtaFullContent, EmbedContent, EventCalendarContent, EventDetailsContent, EventListingContent, EventRegistrationContent, EventSpotlightContent, FaqContent, FormBlockContent, GiftingContent, HeroContent, HeroMedia, ImageGalleryContent, MediaTextContent, NewsletterSignupContent, ShopContent, SingleButtonContent, SiteFooterContent, SiteHeaderContent, SystemBlockContentByKind, SystemBlockContentFor, TeamMembersContent, TestimonialEntryContent, TestimonialsBlockContent, VideoGridContent, ImageOptions, ResolveImageUrlContext, ResolveImageSourceSetOptions, ResolvedImageSourceSet, PageOutline, RouteMap, Theme, ThemeTokens, Media, TipTapNode, LinkValue, RichTextPrimitiveProps, } from './rendering';
-export type { BlockOverrideProps, BlockOverrides, BlockOverrideComponent, KnownSystemBlockOverrides, } from './rendering';
+export type { BlockOverrideProps, BlockOverrideRegistration, BlockOverrideRegistrations, BlockOverrides, BlockOverrideComponent, KnownSystemBlockOverrides, LazyBlockOverrideFactory, LazyBlockOverrideRegistration, } from './rendering';
+export { defineLazyBlockOverride } from './rendering';

package/dist/_dts/sdk/src/next/types.d.ts

@@ -8,7 +8,7 @@ import type { ReactNode } from 'react';
 import type { RiverbankClient } from '../client/types';
 import type { RiverbankSiteConfig } from '../config/types';
 import type { Theme } from '../contracts';
-import type { BlockOverrides } from '../rendering/overrides';
+import type { BlockOverrideRegistrations } from '../rendering/overrides';
 import type { Metadata } from '../metadata/generatePageMetadata';
 import type { LoadContentResult } from '../rendering/helpers/loadContent';
 /**
@@ -182,8 +182,10 @@ export type CreateCatchAllPageOptions = {
     /**
      * Custom block component overrides for rendering.
      * Keys can be full block kind ("block.hero") or short form ("hero").
+     * Wrap client-heavy dynamic imports with defineLazyBlockOverride(); raw
+     * promise-returning functions are not lazy override registrations.
      */
-    blockOverrides?: BlockOverrides;
+    blockOverrides?: BlockOverrideRegistrations;
     /**
      * Override site URL for metadata generation.
      * Defaults to `config.liveUrl` or `config.previewUrl` based on preview mode.

package/dist/_dts/sdk/src/rendering/index.d.ts

@@ -23,7 +23,8 @@ export { ThemeScope, } from './blocks-theme-scope';
 export { buildThemeRuntime, } from './blocks-theme-runtime';
 export type { ComponentRegistry, PageRendererDataContext, PageRendererProps, SdkConfigForRenderer, } from './blocks-page-renderer';
 export type { ThemeScopeProps, } from './blocks-theme-scope';
-export type { BlockOverrideProps, BlockOverrideComponent, BlockOverrides, KnownSystemBlockOverrides, } from './overrides';
+export type { BlockOverrideProps, BlockOverrideComponent, BlockOverrideRegistration, BlockOverrideRegistrations, BlockOverrides, KnownSystemBlockOverrides, LazyBlockOverrideFactory, LazyBlockOverrideRegistration, } from './overrides';
+export { defineLazyBlockOverride } from './overrides';
 /**
  * @example Server-side rendering (Next.js App Router)
  * ```tsx

package/dist/_dts/sdk/src/rendering/overrideResolution.d.ts

@@ -0,0 +1,10 @@
+import type { PageOutline } from '../contracts';
+import { type BlockOverrideRegistrations, type BlockOverrides } from './overrides';
+/**
+ * Resolve only override registrations used by the current page or template.
+ *
+ * Eager components are passed through unchanged. Lazy registrations created
+ * with `defineLazyBlockOverride()` are loaded only after their block kind is
+ * found in the rendered block tree.
+ */
+export declare function resolveBlockOverridesForPage(registrations: BlockOverrideRegistrations | undefined, page: PageOutline | null | undefined): Promise<BlockOverrides | undefined>;

package/dist/_dts/sdk/src/rendering/overrides.d.ts

@@ -25,8 +25,20 @@ type BivariantOverrideComponent<TContent = Record<string, unknown>> = {
     bivarianceHack(props: BlockOverrideProps<TContent, Record<string, unknown>>): React.ReactElement | null;
 }['bivarianceHack'];
 type CompatibleBlockOverrideComponent<TContent = Record<string, unknown>> = BlockOverrideComponent<TContent, Record<string, unknown>> | BivariantOverrideComponent<TContent>;
+export declare const lazyBlockOverrideSymbol: unique symbol;
+export type LazyBlockOverrideFactory<TContent = Record<string, unknown>> = () => Promise<BivariantOverrideComponent<TContent>>;
+export type LazyBlockOverrideRegistration<TContent = Record<string, unknown>> = {
+    readonly [lazyBlockOverrideSymbol]: true;
+    readonly load: LazyBlockOverrideFactory<TContent>;
+};
+export type BlockOverrideRegistration<TContent = Record<string, unknown>> = CompatibleBlockOverrideComponent<TContent> | LazyBlockOverrideRegistration<TContent>;
+export declare function defineLazyBlockOverride<TContent = Record<string, unknown>>(load: LazyBlockOverrideFactory<TContent>): LazyBlockOverrideRegistration<TContent>;
 export type KnownSystemBlockOverrides = {
     [K in keyof SystemBlockContentByKind]?: CompatibleBlockOverrideComponent<SystemBlockContentByKind[K]>;
 };
 export type BlockOverrides = KnownSystemBlockOverrides & Record<string, CompatibleBlockOverrideComponent<Record<string, unknown>>>;
+export type KnownSystemBlockOverrideRegistrations = {
+    [K in keyof SystemBlockContentByKind]?: BlockOverrideRegistration<SystemBlockContentByKind[K]>;
+};
+export type BlockOverrideRegistrations = KnownSystemBlockOverrideRegistrations & Record<string, BlockOverrideRegistration<Record<string, unknown>>>;
 export {};

package/dist/_dts/sdk/src/version.d.ts

@@ -8,4 +8,4 @@
  * 1. This constant
  * 2. The "version" field in package.json
  */
-export declare const SDK_VERSION = "0.70.2";
+export declare const SDK_VERSION = "0.70.3";