@riverbankcms/sdk 0.136.0 → 0.138.0

package/dist/_dts/block-form/src/FormRenderer.d.ts

@@ -28,6 +28,8 @@ export interface FormRendererProps {
      * These paths should refer to existing data within the form values (no duplication).
      */
     promotedFields?: string[];
+    /** Field path whose nested owners should be revealed for editor focus. */
+    focusPath?: string | null;
 }
 /**
  * FormRenderer - Renders a list of fields using the widget registry
@@ -35,4 +37,4 @@ export interface FormRendererProps {
  * Works with any field source (manifests, custom configs, etc.)
  * Works with any backend (RHF, Zustand store, etc.)
  */
-export declare function FormRenderer({ fields, backend, className, fieldWrapper, widgetOverrides, blockKind, showSettingsTrigger, promotedFields, }: FormRendererProps): ReactNode;
+export declare function FormRenderer(props: FormRendererProps): ReactNode;

package/dist/_dts/block-form/src/backend/store-backend.d.ts

@@ -50,8 +50,9 @@ interface EditorStoreState {
     };
     arrayKeys: ArrayKeysManager;
     requestFocus?: (payload: {
+        kind: 'main-field';
         blockId: EditorBlockId;
-        fieldPath?: string | null;
+        fieldPath: string;
     }) => void;
 }
 /**

package/dist/_dts/block-form/src/backend/types.d.ts

@@ -24,6 +24,8 @@ export interface ZustandLikeStore<TState = unknown> {
     subscribe: (callback: () => void) => () => void;
 }
 export type SetValueOptions = {
+    /** Logical field edited when a structured write replaces an ancestor value. */
+    editedPath?: string;
     shouldDirty?: boolean;
     shouldTouch?: boolean;
     shouldValidate?: boolean;

package/dist/_dts/block-form/src/context/FormFocusContext.d.ts

@@ -0,0 +1,7 @@
+import { type ReactNode } from 'react';
+export declare function FormFocusProvider({ fieldPath, children, }: Readonly<{
+    fieldPath: string | null;
+    children: ReactNode;
+}>): import("react").JSX.Element;
+export declare function useFormFocusPath(): string | null;
+export declare function focusPathIsWithin(focusPath: string | null, ownerPath: string): boolean;

package/dist/_dts/block-form/src/index.d.ts

@@ -3,6 +3,8 @@ export { mergeManifestWithSdkOptions } from './manifest/mergeManifestWithSdkOpti
 export { WIDGET_NAMES } from './widgets/constants';
 export * from './utils/fieldHelpers';
 export { evaluateVisibility } from './utils/evaluateVisibility';
+export { derivePromotedFieldPlan, prunePromotedFields, type PromotedFieldPlan, } from './utils/promotedFieldPlan';
+export { resolvePromotedFields } from './utils/resolvePromotedFields';
 export type { FormRendererProps } from './FormRenderer';
 export type { ManifestFormProps } from './manifest/ManifestForm';
 export type { FieldWidgetComponent, FieldWidgetProps } from './fields/props';

package/dist/_dts/block-form/src/manifest/ManifestForm.d.ts

@@ -20,6 +20,7 @@ export interface ManifestFormProps {
     blockKind?: string;
     /** Show inline settings trigger for non-content intents (default: true) */
     showSettingsTrigger?: boolean;
+    focusPath?: string | null;
 }
 /**
  * ManifestForm - Renders form fields from a block manifest
@@ -34,4 +35,4 @@ export interface ManifestFormProps {
  * <ManifestForm manifest={blockManifest} backend={backend} />
  * ```
  */
-export declare function ManifestForm({ manifest, className, role, backend, widgetOverrides, blockKind, showSettingsTrigger, }: ManifestFormProps): import("react").JSX.Element | null;
+export declare function ManifestForm({ manifest, className, role, backend, widgetOverrides, blockKind, showSettingsTrigger, focusPath, }: ManifestFormProps): import("react").JSX.Element | null;

package/dist/_dts/block-form/src/utils/promotedFieldBackend.d.ts

@@ -0,0 +1,8 @@
+import type { FormBackend } from '../backend/types';
+import type { ResolvedPromotedField } from './resolvePromotedFields';
+/**
+ * Replace the outermost owning tab object in one backend/autosave update.
+ * Each edit deep-clones that subtree, including nested repeater-item data;
+ * editedPath preserves leaf validation visibility despite the ancestor write.
+ */
+export declare function createPromotedFieldBackend(backend: FormBackend, promoted: ResolvedPromotedField): FormBackend;

package/dist/_dts/block-form/src/utils/promotedFieldPlan.d.ts

@@ -0,0 +1,18 @@
+import type { FieldConfig } from '../fields/types';
+import { type ResolvedPromotedField } from './resolvePromotedFields';
+export type PromotedFieldPlan = Readonly<{
+    beforeContent: readonly ResolvedPromotedField[];
+    afterContent: readonly ResolvedPromotedField[];
+    promotedPaths: ReadonlySet<string>;
+    topLevelFieldIds: ReadonlySet<string>;
+}>;
+/**
+ * Plans the main-form shortcuts from one manifest field list.
+ *
+ * Explicit shortcuts keep their established before-content position. Required
+ * top-level Display/Behavior fields are appended after content so the Form
+ * block reads Title, Intro, Form. Nested required fields stay with their owner
+ * container instead of being flattened into a misleading standalone control.
+ */
+export declare function derivePromotedFieldPlan(fields: FieldConfig[], explicitPaths: readonly string[] | undefined, getValue?: (path: string) => unknown): PromotedFieldPlan;
+export declare function prunePromotedFields(fields: readonly FieldConfig[], promotedPaths: ReadonlySet<string>, parentPath?: string): FieldConfig[];

package/dist/_dts/block-form/src/utils/resolvePromotedFields.d.ts

@@ -1,6 +1,13 @@
 import type { FieldConfig } from '../fields/types';
 import type { TabDefinition } from '../widgets/TabGroupField/types';
+export type PromotedTabSelection = {
+    readonly parentPath: string;
+    readonly controlField: string;
+    readonly tabId: string;
+};
 export type ResolvedPromotedField = {
+    /** Ancestor selections required when writing through this shortcut. */
+    tabSelections: readonly PromotedTabSelection[];
     /** Absolute backend path to read/write (e.g. `_sectionStyles.background.image`) */
     path: string;
     /** Field config to render at the path */
@@ -19,4 +26,4 @@ export type ResolvedPromotedField = {
  *   uses greedy matching against child IDs to support those paths.
  * - Array indexes in paths (e.g. `items.0.title`) are ignored for matching.
  */
-export declare function resolvePromotedFields(fields: FieldConfig[], promotedPaths: string[] | undefined): ResolvedPromotedField[];
+export declare function resolvePromotedFields(fields: FieldConfig[], promotedPaths: string[] | undefined, getValue: (path: string) => unknown): ResolvedPromotedField[];

package/dist/_dts/blocks/src/BlockErrorBoundary.d.ts

@@ -0,0 +1,46 @@
+import * as React from 'react';
+/**
+ * Enough of the render context to find the offending block from a log line.
+ * Deliberately a plain serialisable record: this component is a client
+ * reference, so nothing that crosses into it may be a function.
+ */
+export type BlockErrorRecord = Readonly<{
+    siteId: string | null;
+    pageId: string | null;
+    blockId: string | null;
+    blockKind: string;
+}>;
+export type BlockErrorBoundaryProps = Readonly<{
+    /**
+     * What to show in the block's place once it has thrown. The caller resolves
+     * it through `presentNotRenderableBlock`, so the audience policy stays in one
+     * module — `null` for a public visitor, the diagnostic for an author.
+     */
+    fallback: React.ReactNode;
+    record: BlockErrorRecord;
+    /**
+     * Identity of the entry being rendered. When it changes the boundary forgets
+     * a previous failure, so a block the author has since fixed renders again.
+     * Keying the *element* on the block id is not enough for that — the block id
+     * is stable across the very edit that fixes it.
+     */
+    resetKey: unknown;
+    children: React.ReactNode;
+}>;
+export declare const BlockErrorBoundary: React.ComponentType<Readonly<{
+    /**
+     * What to show in the block's place once it has thrown. The caller resolves
+     * it through `presentNotRenderableBlock`, so the audience policy stays in one
+     * module — `null` for a public visitor, the diagnostic for an author.
+     */
+    fallback: React.ReactNode;
+    record: BlockErrorRecord;
+    /**
+     * Identity of the entry being rendered. When it changes the boundary forgets
+     * a previous failure, so a block the author has since fixed renders again.
+     * Keying the *element* on the block id is not enough for that — the block id
+     * is stable across the very edit that fixes it.
+     */
+    resetKey: unknown;
+    children: React.ReactNode;
+}>>;

package/dist/_dts/blocks/src/PageRenderer.d.ts

@@ -5,152 +5,13 @@ import type { Theme } from '../../theme-core/src/schema';
 import type { SdkCustomBlock } from './system/manifest/schema';
 import type { ThemeTokens } from './system/theme';
 import type { RouteMap } from './system/transforms';
-import { type MediaAssetIndexItem, type ResolveImageUrlContext, type ResolveImageUrlContextInput } from './system/runtime/nodes/media';
-import type { BookingOfferingPresetSummary } from './system/blocks/offerings-preview/model';
 import { type PageBoundaryWrapper, type PageRuntimeBoundary } from './pageRendererBoundaries';
+import type { BlockOverrides, PageRendererDataContext, SdkConfigForRenderer } from './pageRendererContracts';
 import { type RenderablePageOutline } from './pageRenderAdmission';
 export type { PageBlockRenderAdmissionError, RenderablePageBlock, RenderablePageOutline, } from './pageRenderAdmission';
+export type { BlockOverrideComponent, BlockOverrideProps, BlockOverrides, EntrySubrouteContextData, OccurrenceContextData, SdkConfigForRenderer, } from './pageRendererContracts';
 export { MissingBlockOverrideError } from './pageRenderingMode';
 export type { PageBlockPosition, PageRuntimeBoundary, } from './pageRendererBoundaries';
-/**
- * Occurrence context for event pages.
- * Passed through to blocks that need occurrence information (e.g., event-registration).
- */
-export type OccurrenceContextData = import('../../core/src/index').EventOccurrenceContextData;
-/**
- * Event-occurrence subroute context.
- */
-export type EntrySubrouteContextData = import('../../core/src/index').EventPageSubrouteContext;
-type PageRendererDataContext = {
-    siteId?: string;
-    pageId?: string;
-    resolvedData?: Record<string, Record<string, unknown>>;
-    previewStage?: 'published' | 'preview';
-    previewToken?: string | null;
-    routes?: RouteMap;
-    pagesByIdentifier?: Record<string, string>;
-    entriesByIdentifier?: Record<string, Record<string, string>>;
-    occurrenceContext?: OccurrenceContextData | null;
-    entrySubrouteContext?: EntrySubrouteContextData | null;
-    contentEntry?: Record<string, unknown> | null;
-    pageSurface?: Record<string, unknown> | null;
-    subject?: import('../../core/src/index').EventPageSurfaceSubjectWire | null;
-    editableRouteMetadataFieldIds?: ReadonlyArray<string> | null;
-    supabaseUrl?: string;
-    mediaAssets?: readonly MediaAssetIndexItem[];
-    imageResolveContext?: ResolveImageUrlContextInput;
-    apiBaseUrl?: string;
-    portalToken?: string | null;
-    bookingOfferingPresets?: readonly BookingOfferingPresetSummary[];
-    bookingTimeZone?: string;
-    eventRegistrationOverlayEnabled?: boolean;
-};
-/**
- * Props passed to block override components.
- *
- * These props are RSC-safe (no functions) so overrides can be Client Components.
- * Unlike internal SDK block components, overrides don't receive `registry` or
- * `fragmentRegistry` which contain function references that can't cross the
- * RSC serialization boundary.
- *
- * @example
- * ```tsx
- * 'use client';
- *
- * import type { BlockOverrideProps, HeroContent } from '@riverbankcms/sdk/rendering';
- *
- * export function CustomHero({ content, theme, data }: BlockOverrideProps<HeroContent>) {
- *   const [expanded, setExpanded] = useState(false);
- *   return <div>...</div>;
- * }
- * ```
- */
-export type BlockOverrideProps<TContent = Record<string, unknown>> = {
-    /** Block content data */
-    content: TContent;
-    /** Theme tokens for styling */
-    theme?: ThemeTokens;
-    /** Full theme configuration */
-    themeConfig?: Theme;
-    /** Pre-fetched data from data loaders */
-    data?: Record<string, unknown>;
-    /** Site UUID (useful for media URL resolution in override components) */
-    siteId?: string;
-    /** Dashboard API URL for client-side block runtime calls. */
-    apiBaseUrl?: string;
-    /** Canonical site timezone for calendar/date behavior. */
-    bookingTimeZone?: string;
-    /** Customer portal token for Bearer-authenticated block runtime calls. */
-    portalToken?: string | null;
-    /** Preview bearer token for preview-aware block runtime calls. */
-    previewToken?: string | null;
-    /** Render stage for preview-aware block runtime calls. */
-    stage?: 'published' | 'preview';
-    /** Event-occurrence context for template-aware block overrides. */
-    occurrenceContext?: OccurrenceContextData | null;
-    /** Generic entry subroute context for template-aware block overrides. */
-    entrySubrouteContext?: EntrySubrouteContextData | null;
-    /** Content entry context for template-aware block overrides. */
-    contentEntry?: Record<string, unknown> | null;
-    /** Native page-surface context for template-aware block overrides. */
-    pageSurface?: Record<string, unknown> | null;
-    /** Subject descriptor for native page-surface block overrides. */
-    subject?: import('../../core/src/index').EventPageSurfaceSubjectWire | null;
-    /** Supabase project URL (useful for media URL resolution in override components) */
-    supabaseUrl?: string;
-    /** Full image-resolution context including canonical media sidecars. */
-    imageResolveContext?: ResolveImageUrlContext;
-    /** Block instance ID (null for unsaved blocks) */
-    blockId: string | null;
-    /** Block kind identifier (e.g., "block.hero" or "custom.my-block") */
-    blockKind: string;
-};
-/**
- * Block override component type.
- *
- * Override components can be either Server Components or Client Components.
- * They receive only serializable props (no functions) to support RSC boundaries.
- *
- * @example Server Component override
- * ```tsx
- * export function CustomHero({ content, theme, data }: BlockOverrideProps<HeroContent>) {
- *   return <div className="custom-hero">...</div>;
- * }
- * ```
- *
- * @example Client Component override
- * ```tsx
- * 'use client';
- *
- * export function CustomHero({ content, theme, data }: BlockOverrideProps<HeroContent>) {
- *   const [state, setState] = useState(null);
- *   return <div className="custom-hero">...</div>;
- * }
- * ```
- */
-export type BlockOverrideComponent = React.ComponentType<BlockOverrideProps<unknown>>;
-/**
- * Map of block kinds to custom override components.
- * Keys can be either:
- * - Full block kind: "block.hero"
- * - Short form: "hero" (will match "block.hero")
- *
- * @example
- * ```tsx
- * const overrides: BlockOverrides = {
- *   'hero': CustomHero,        // CustomHero uses BlockOverrideProps<HeroContent>
- *   'body-text': CustomBodyText, // CustomBodyText uses BlockOverrideProps<BodyTextContent>
- * };
- * ```
- */
-export type BlockOverrides = Record<string, BlockOverrideComponent>;
-/**
- * SDK site configuration for custom block rendering.
- * Minimal type containing only what PageRenderer needs.
- */
-export type SdkConfigForRenderer = {
-    customBlocks?: SdkCustomBlock[];
-};
 type PageRendererCommonProps<TPage> = {
     page: TPage | null;
     runtimeBoundaries?: readonly PageRuntimeBoundary[];

package/dist/_dts/blocks/src/contracts/index.d.ts

@@ -1,6 +1,8 @@
 export type { AnyBlockRuntimeDefinition, BlockRenderKind, BlockRuntimeDefinition, ClientOwnedBlockRuntime, Codec, DecodeIssue, DecodeResult, InteractiveBlockRenderKind, InteractiveBlockRuntime, InteractiveRuntimeContracts, ProgressiveBlockRender, ProgressiveBlockRuntime, RuntimeContractsFor, RuntimeDisplay, RuntimeHydration, RuntimeKind, RuntimeRender, RuntimeSource, StaticBlockRuntime, StaticRuntimeContracts, } from './runtime';
 export type { InteractiveIslandProps } from './islands';
 export type { PublicEvent } from '../system/blocks/events/shared/types';
+export { calendarWindowQuerySchema, calendarWindowPageSchema, calendarMonthWindowSchema, calendarMonthKey, calendarMonthDate, calendarWindowMonths, calendarWindowBounds, resolveCalendarWindow, calendarQueryKey, planCalendarMonthRanges, CALENDAR_SSR_PAGE_SIZE, CALENDAR_CLIENT_PAGE_SIZE } from '../system/blocks/events/shared/calendarWindow';
+export type { CalendarWindowQuery, CalendarWindowRequest, CalendarWindowPage, CalendarMonthWindow, CalendarSourceCursor, CalendarPageProgress, CalendarFilterInput } from '../system/blocks/events/shared/calendarWindow';
 export type { AccordionIslandProps, CarouselIslandProps, EventDetailsIslandProps, EventDetailsOccurrenceContext, HeaderSectionIslandProps, LocationMapIslandProps, } from './non-block-islands';
 export type { HeaderChromeRuntimeContract, HeaderScrollRuntime, } from '../system/runtime/header/runtimeContract';
 export type { BookingFormConfig, BookingFormDisplay, BookingFormHydration, BookingFormInteractiveIslandProps, BookingFormService, CartDisplay, CartHydration, CartInteractiveIslandProps, CartLineDisplay, CheckoutDisplay, CheckoutHydration, CheckoutInteractiveIslandProps, EventCalendarDisplay, EventCalendarHydration, EventCalendarInteractiveIslandProps, EventCombinedDisplay, EventCombinedHydration, EventCombinedInteractiveIslandProps, EventRegistrationDisplay, EventRegistrationHydration, EventRegistrationInteractiveIslandProps, EventListingDisplay, EventListingHydration, EventListingInteractiveIslandProps, FormDisplay, FormHydration, FormInteractiveIslandProps, MembershipCardDisplay, NewsletterFormDisplay, NewsletterFormHydration, NewsletterFormInteractiveIslandProps, PassCardDisplay, PassesMembershipsDisplay, PassesMembershipsHydration, ProductCardDisplay, ProductDetailDisplay, ProductDetailInteractiveIslandProps, ProductDetailHydration, ProductListDisplay, ProductListInteractiveIslandProps, ProductListHydration, ProductVariantOptionDisplay, ShopInteractiveIslandProps, } from './proof-block-islands';

package/dist/_dts/blocks/src/contracts/proof-block-islands.d.ts

@@ -280,7 +280,7 @@ export declare const proofBlockIslandCodecs: {
                     showMap: boolean;
                     showCapacity: boolean;
                     orientation: import("..").CardOrientation;
-                    events: readonly import(".").PublicEvent[];
+                    events: readonly import("../../../api/src/index").PublicEvent[];
                 }>;
                 hydration: Readonly<{
                     siteId: string;
@@ -325,7 +325,7 @@ export declare const proofBlockIslandCodecs: {
                     showMap: boolean;
                     showCapacity: boolean;
                     orientation: import("..").CardOrientation;
-                    events: readonly import(".").PublicEvent[];
+                    events: readonly import("../../../api/src/index").PublicEvent[];
                 }>;
                 hydration: Readonly<{
                     siteId: string;
@@ -359,6 +359,7 @@ export declare const proofBlockIslandCodecs: {
             } & Readonly<{
                 display: EventCalendarDisplay;
                 hydration: Readonly<{
+                    calendarWindow?: import(".").CalendarWindowPage;
                     siteId: string;
                     stage?: "preview" | "published";
                     prefetchedEvents: boolean;
@@ -387,6 +388,7 @@ export declare const proofBlockIslandCodecs: {
             } & Readonly<{
                 display: EventCalendarDisplay;
                 hydration: Readonly<{
+                    calendarWindow?: import(".").CalendarWindowPage;
                     siteId: string;
                     stage?: "preview" | "published";
                     prefetchedEvents: boolean;
@@ -881,6 +883,7 @@ export declare const runtimeIslandCodecs: {
             } & Readonly<{
                 display: EventCombinedDisplay;
                 hydration: Readonly<{
+                    calendarWindow?: import(".").CalendarWindowPage;
                     siteId: string;
                     stage?: "preview" | "published";
                     prefetchedEvents: boolean;
@@ -909,6 +912,7 @@ export declare const runtimeIslandCodecs: {
             } & Readonly<{
                 display: EventCombinedDisplay;
                 hydration: Readonly<{
+                    calendarWindow?: import(".").CalendarWindowPage;
                     siteId: string;
                     stage?: "preview" | "published";
                     prefetchedEvents: boolean;
@@ -1198,7 +1202,7 @@ export declare const runtimeIslandCodecs: {
                     showMap: boolean;
                     showCapacity: boolean;
                     orientation: import("..").CardOrientation;
-                    events: readonly import(".").PublicEvent[];
+                    events: readonly import("../../../api/src/index").PublicEvent[];
                 }>;
                 hydration: Readonly<{
                     siteId: string;
@@ -1243,7 +1247,7 @@ export declare const runtimeIslandCodecs: {
                     showMap: boolean;
                     showCapacity: boolean;
                     orientation: import("..").CardOrientation;
-                    events: readonly import(".").PublicEvent[];
+                    events: readonly import("../../../api/src/index").PublicEvent[];
                 }>;
                 hydration: Readonly<{
                     siteId: string;
@@ -1277,6 +1281,7 @@ export declare const runtimeIslandCodecs: {
             } & Readonly<{
                 display: EventCalendarDisplay;
                 hydration: Readonly<{
+                    calendarWindow?: import(".").CalendarWindowPage;
                     siteId: string;
                     stage?: "preview" | "published";
                     prefetchedEvents: boolean;
@@ -1305,6 +1310,7 @@ export declare const runtimeIslandCodecs: {
             } & Readonly<{
                 display: EventCalendarDisplay;
                 hydration: Readonly<{
+                    calendarWindow?: import(".").CalendarWindowPage;
                     siteId: string;
                     stage?: "preview" | "published";
                     prefetchedEvents: boolean;
@@ -1831,7 +1837,7 @@ export declare const runtimeIslandCodecs: {
         encode: (value: Readonly<{
             occurrenceContext?: import("./non-block-islands").EventDetailsOccurrenceContext | null;
             subject?: import("../system/runtime/nodes/event-registration/eventScope").EventRegistrationPageSurfaceSubject | null;
-            events?: readonly import(".").PublicEvent[] | null;
+            events?: readonly import("../../../api/src/index").PublicEvent[] | null;
             showVenue?: boolean;
             showMap?: boolean;
             showOtherDates?: boolean;
@@ -1855,7 +1861,7 @@ export declare const runtimeIslandCodecs: {
         decode: (input: unknown) => import("./runtime").DecodeResult<Readonly<{
             occurrenceContext?: import("./non-block-islands").EventDetailsOccurrenceContext | null;
             subject?: import("../system/runtime/nodes/event-registration/eventScope").EventRegistrationPageSurfaceSubject | null;
-            events?: readonly import(".").PublicEvent[] | null;
+            events?: readonly import("../../../api/src/index").PublicEvent[] | null;
             showVenue?: boolean;
             showMap?: boolean;
             showOtherDates?: boolean;

package/dist/_dts/blocks/src/index.d.ts

@@ -1,4 +1,5 @@
 export { default as PageRenderer, EditorPageRenderer } from './PageRenderer';
+export type { RenderAudience as PageRenderAudience } from './pageRenderAudience';
 export { createCustomBlockRegistry, mergeBlockDescriptorsWithRegistry, planCustomBlockRegistryResolution, transformToBlockDescriptor, } from './customBlockRegistry';
 export type { CustomBlockConflictReason, CustomBlockManifestSource, CustomBlockRegistry, CustomBlockRegistryConflict, CustomBlockRegistryEntry, CustomBlockRegistryResolutionPlan, CustomBlockSourcePolicy, ResolvedCustomBlockManifest, SdkConfigForBlockPicker, } from './customBlockRegistry';
 export type { BlockOverrideComponent, BlockOverrideProps, BlockOverrides, EntrySubrouteContextData, EditorPageRendererProps, PageBlockRenderAdmissionError, PageRendererProps, RenderablePageBlock, RenderablePageOutline, OccurrenceContextData, PageBlockPosition, PageRuntimeBoundary, SdkConfigForRenderer, } from './PageRenderer';

package/dist/_dts/blocks/src/pageRenderAudience.d.ts

@@ -0,0 +1,54 @@
+import * as React from 'react';
+import type { PageBlockRenderAdmissionError } from './pageRenderAdmission';
+/**
+ * Who is looking at this render.
+ *
+ * The split is structural, not environmental: `PageRenderer` serves public
+ * visitors and `EditorPageRenderer` serves authoring surfaces. Deriving it from
+ * `process.env.NODE_ENV` would be wrong in both directions — a production
+ * dashboard preview is authoring, and a development public page is still public.
+ */
+export type RenderAudience = 'public' | 'authoring';
+/**
+ * Why a block could not be rendered.
+ *
+ * A closed union so a new failure mode has to pick a reason, and therefore
+ * inherits the omission policy rather than inventing a sixth fallback string.
+ *
+ * `invalid-admission`, `missing-definition` and `missing-layout` are decided
+ * ahead of render by `buildPageRenderPlan`. `editor-unpreviewable` and
+ * `render-threw` are only knowable while rendering the block itself.
+ */
+export type NotRenderableReason = Readonly<{
+    kind: 'invalid-admission';
+    blockKind: string;
+    error: PageBlockRenderAdmissionError;
+}> | Readonly<{
+    kind: 'missing-definition';
+    blockKind: string;
+    isCustom: boolean;
+}> | Readonly<{
+    kind: 'missing-layout';
+    blockKind: string;
+    isCustom: boolean;
+}> | Readonly<{
+    kind: 'editor-unpreviewable';
+    blockKind: string;
+}> | Readonly<{
+    kind: 'render-threw';
+    blockKind: string;
+}>;
+/**
+ * The single policy for what a non-renderable block looks like.
+ *
+ * Public visitors never see renderer diagnostics, so every reason omits.
+ * Authoring surfaces keep the wording they have always had — the strings below
+ * are moved verbatim from the five former `fallback()` call sites.
+ */
+export declare function presentNotRenderableBlock(reason: NotRenderableReason, audience: RenderAudience): React.ReactNode | null;
+/**
+ * The empty-page notice. Authoring-only for the same reason as the block
+ * diagnostics: "No blocks found." is a message for whoever is building the
+ * page, not for whoever is reading it.
+ */
+export declare function presentEmptyPage(audience: RenderAudience): React.ReactNode | null;

package/dist/_dts/blocks/src/pageRenderDiagnostics.d.ts

@@ -0,0 +1,26 @@
+import type { PresentationBlock } from './pageRenderAdmission';
+import type { OmittedBlockDebugFields, PageRenderPlan, PlanTimeNotRenderableReason } from './pageRenderPlan';
+/** The slice of render context a diagnostic record needs to be traceable. */
+export type PageRenderDiagnosticContext = Readonly<{
+    siteId?: string;
+    pageId?: string;
+}> | undefined;
+/**
+ * Emits one structured record per omitted block, per server render pass.
+ *
+ * Server-only by decision D3: public pages are server-rendered, and this is the
+ * runtime whose logger transport reaches centralised collection. A browser-side
+ * record would not, and re-render/hydration would multiply it. The cost is that
+ * an omission only a client navigation can see goes unlogged.
+ *
+ * Deliberately *not* inside the plan's `useMemo` — React makes no promises about
+ * when a memo recomputes, so a log placed there is neither reliable nor bounded.
+ */
+export declare function logOmittedBlocks(plan: PageRenderPlan, dataContext: PageRenderDiagnosticContext): void;
+/**
+ * Unlike the plan-time omissions this one genuinely can fire per re-render —
+ * it is raised where the failure happens, and no once-ness is claimed for it.
+ */
+export declare function logRenderThrew(block: PresentationBlock, dataContext: PageRenderDiagnosticContext): void;
+/** The authoring-side equivalent, where the block stays in the entry list. */
+export declare function debugCustomBlockDiagnostic(reason: PlanTimeNotRenderableReason, block: PresentationBlock, debug: OmittedBlockDebugFields): void;

package/dist/_dts/blocks/src/pageRenderPlan.d.ts

@@ -0,0 +1,116 @@
+import { getBlockDefinition } from './system';
+import type { SdkCustomBlock } from './system/manifest/schema';
+import type { PresentationBlock, PresentationPageOutline } from './pageRenderAdmission';
+import { type PageRuntimeBoundary } from './pageRendererBoundaries';
+import type { BlockOverrideComponent, BlockOverrides, SdkConfigForRenderer } from './pageRendererContracts';
+import type { NotRenderableReason, RenderAudience } from './pageRenderAudience';
+type ResolvedBlockDefinition = NonNullable<ReturnType<typeof getBlockDefinition>>;
+type PlanEntryCommon = Readonly<{
+    block: PresentationBlock;
+    renderableContent: Record<string, unknown>;
+}>;
+/**
+ * One block's place in the render.
+ *
+ * A discriminated union rather than a record with optional fields, so the three
+ * render paths that already exist in `MemoBlockSection` are visible in the type
+ * and no case needs a cast or a fabricated definition:
+ *
+ * - `renderable`    — a definition resolved; may also have an override
+ * - `override-only` — no definition, but the caller supplied a component
+ *                     (the deliberate escape hatch for stale runtime payloads)
+ * - `diagnostic`    — cannot render; authoring plans only
+ *
+ * Public plans contain no `diagnostic` entries; those blocks are in `omitted`.
+ */
+export type PageBlockRenderPlanEntry = (PlanEntryCommon & Readonly<{
+    kind: 'renderable';
+    definition: ResolvedBlockDefinition;
+    override: BlockOverrideComponent | undefined;
+    variantKey: string | null;
+    managesOwnWrapper: boolean;
+}>) | (PlanEntryCommon & Readonly<{
+    kind: 'override-only';
+    override: BlockOverrideComponent;
+}>) | (PlanEntryCommon & Readonly<{
+    kind: 'diagnostic';
+    reason: PlanTimeNotRenderableReason;
+    debug: OmittedBlockDebugFields;
+}>);
+/**
+ * The subset of reasons the plan can decide ahead of render.
+ *
+ * `editor-unpreviewable` and `render-threw` are only knowable while rendering
+ * the block, so they can never describe an omission. Narrowing the type here
+ * means the overrides-only replay in PageRendererCore switches over three
+ * cases exhaustively instead of trusting a comment.
+ */
+export type PlanTimeNotRenderableReason = Extract<NotRenderableReason, {
+    kind: 'invalid-admission' | 'missing-definition' | 'missing-layout';
+}>;
+export type OmittedPageBlock = Readonly<{
+    blockId: string | null;
+    blockKind: string;
+    reason: PlanTimeNotRenderableReason;
+    /**
+     * The override resolved for this kind, if any. Carried so the overrides-only
+     * contract can be replayed without assuming "omitted implies no override" —
+     * an assumption that is true today only because of how `planBlock` branches.
+     */
+    override: BlockOverrideComponent | undefined;
+    /** Registry sizes at the time of the decision, for DEBUG_CUSTOM_BLOCKS. */
+    debug: OmittedBlockDebugFields;
+}>;
+export type OmittedBlockDebugFields = Readonly<{
+    hasOverride: boolean;
+    sdkCustomBlocksCount: number;
+    dbCustomBlocksCount: number;
+    manifestKeys: readonly string[] | null;
+}>;
+export type PageRenderPlan = Readonly<{
+    entries: readonly PageBlockRenderPlanEntry[];
+    omitted: readonly OmittedPageBlock[];
+    runtimeBoundaries: readonly PageRuntimeBoundary[] | undefined;
+}>;
+export type BuildPageRenderPlanInput = Readonly<{
+    page: PresentationPageOutline;
+    audience: RenderAudience;
+    runtimeBoundaries: readonly PageRuntimeBoundary[] | undefined;
+    previewStage: 'published' | 'preview';
+    sdkConfig: SdkConfigForRenderer | null | undefined;
+    customBlocks: readonly SdkCustomBlock[] | undefined;
+    blockOverrides: BlockOverrides | undefined;
+}>;
+/**
+ * Decides, once per page render, which blocks can render and what happens to
+ * the ones that cannot.
+ *
+ * Pure. Effects — logging in particular — belong at the call site, because this
+ * runs inside a `useMemo` whose recomputation React makes no promises about.
+ */
+export declare function buildPageRenderPlan(input: BuildPageRenderPlanInput): PageRenderPlan;
+/**
+ * Re-points section boundaries across omitted blocks.
+ *
+ * Boundaries are keyed by adjacent block-id *pairs*, so dropping B from
+ * [A, B, C] does not merely remove B's boundaries — it removes the boundary
+ * between the survivors, because no `A→C` key was ever compiled.
+ *
+ * Per decision D2 the treatment for a merged gap comes from the boundary
+ * entering the omitted run (`A→firstOmitted`), falling back to the one leaving
+ * it (`lastOmitted→C`). The destination surface is a separate question: only
+ * the exiting boundary knows what C looks like, so the merged boundary ends on
+ * that endpoint rather than on the omitted block's. In the exiting-only
+ * fallback the origin remains an approximation: `from` is the omitted block's
+ * surface, because no compiled boundary carries A's. The hosted path no longer
+ * needs this at all (site-renderer admits blocks before compiling boundaries);
+ * it remains the safety net for an SDK whose compiled boundaries predate an
+ * omission.
+ */
+export declare function retargetBoundariesAcrossOmissions(input: Readonly<{
+    boundaries: readonly PageRuntimeBoundary[] | undefined;
+    originalBlocks: readonly PresentationBlock[];
+    survivingBlocks: ReadonlySet<PresentationBlock>;
+    previewStage: 'published' | 'preview';
+}>): readonly PageRuntimeBoundary[] | undefined;
+export {};