@actuate-media/cms-admin 0.41.0 → 0.42.1

package/src/__tests__/views/page-section-editor.test.tsx

@@ -12,6 +12,7 @@ vi.mock('../../lib/page-editor-service.js', async (importOriginal) => {
 })
 
 const { PageSectionEditor } = await import('../../views/page-editor/PageSectionEditor.js')
+const { AdminSectionRenderersProvider } = await import('../../views/page-editor/sections/index.js')
 
 const validConfig = {
   collections: {
@@ -121,6 +122,34 @@ describe('PageSectionEditor structure mode', () => {
     expect(screen.getByRole('button', { name: /Preview structure/ })).toBeTruthy()
   })
 
+  it('stays out of structure mode when a custom renderer is registered for the type', async () => {
+    fetchPageForEditor.mockResolvedValue(
+      loadedPage([
+        { id: 's1', sectionType: 'hero', name: 'Hero' },
+        { id: 's2', sectionType: 'opal-flip-cards', name: 'Flip Cards' },
+      ]),
+    )
+    render(
+      <AdminSectionRenderersProvider
+        value={{ 'opal-flip-cards': () => <div data-testid="opal-canvas" /> }}
+      >
+        <PageSectionEditor
+          documentId="p1"
+          config={validConfig}
+          onNavigate={() => {}}
+          session={{}}
+        />
+      </AdminSectionRenderersProvider>,
+    )
+
+    await screen.findByText('Sections')
+    // The registered renderer draws the section, so the canvas is no longer
+    // structural for this page.
+    expect(screen.getByTestId('opal-canvas')).toBeTruthy()
+    expect(screen.queryByText(/Structure view/)).toBeNull()
+    expect(screen.getByRole('button', { name: 'View draft on site' })).toBeTruthy()
+  })
+
   it('exposes a version history button for saved pages', async () => {
     fetchPageForEditor.mockResolvedValue(
       loadedPage([{ id: 's1', sectionType: 'hero', name: 'Hero' }]),

package/src/__tests__/views/portal-container.test.tsx

@@ -0,0 +1,56 @@
+// @vitest-environment happy-dom
+import { afterEach, describe, expect, it } from 'vitest'
+import { cleanup, render, screen } from '@testing-library/react'
+import { ConfirmDangerousSettingDialog } from '../../views/settings/components.js'
+import { adminPortalContainer } from '../../lib/portal-container.js'
+
+/**
+ * Regression: theme tokens only exist under `.actuate-admin` (theme.css), so
+ * Radix portals must mount INSIDE that scope. Portaling to document.body
+ * (Radix's default) produced unstyled overlays — transparent cards, colorless
+ * destructive buttons, broken dark mode.
+ */
+
+afterEach(cleanup)
+
+function renderInAdminRoot(ui: React.ReactElement) {
+  const root = document.createElement('div')
+  root.className = 'actuate-admin'
+  document.body.appendChild(root)
+  return render(ui, { container: root })
+}
+
+describe('adminPortalContainer', () => {
+  it('resolves the admin root element', () => {
+    const root = document.createElement('div')
+    root.className = 'actuate-admin'
+    document.body.appendChild(root)
+    expect(adminPortalContainer()).toBe(root)
+    root.remove()
+  })
+
+  it('returns undefined when no admin root is mounted', () => {
+    document.querySelectorAll('.actuate-admin').forEach((el) => el.remove())
+    expect(adminPortalContainer()).toBeUndefined()
+  })
+})
+
+describe('portaled overlays mount inside the admin theme scope', () => {
+  it('renders the dangerous-setting confirm dialog within .actuate-admin', async () => {
+    renderInAdminRoot(
+      <ConfirmDangerousSettingDialog
+        open
+        title="Block this production site from search engines?"
+        description="This may prevent search engines from indexing your production site."
+        confirmLabel="Enable No Index"
+        onConfirm={() => {}}
+        onCancel={() => {}}
+      />,
+    )
+
+    const title = await screen.findByText(/Block this production site/)
+    // The dialog content must live inside the token scope, otherwise
+    // bg-card / text-warning / bg-destructive resolve to nothing.
+    expect(title.closest('.actuate-admin')).not.toBeNull()
+  })
+})

package/src/components/LocaleSwitcher.tsx

@@ -2,6 +2,7 @@
 
 import { Globe, Check, ChevronDown } from 'lucide-react'
 import * as DropdownMenu from '@radix-ui/react-dropdown-menu'
+import { adminPortalContainer } from '../lib/portal-container.js'
 import { useLocale } from './LocaleProvider.js'
 
 export function LocaleSwitcher() {
@@ -26,7 +27,7 @@ export function LocaleSwitcher() {
         </button>
       </DropdownMenu.Trigger>
 
-      <DropdownMenu.Portal>
+      <DropdownMenu.Portal container={adminPortalContainer()}>
         <DropdownMenu.Content
           className="z-50 min-w-[160px] rounded-lg border border-[var(--border)] bg-[var(--popover)] p-1 text-[var(--popover-foreground)] shadow-lg"
           align="end"

package/src/components/SEOPanel.tsx

@@ -1,6 +1,7 @@
 'use client'
 
 import * as Select from '@radix-ui/react-select'
+import { adminPortalContainer } from '../lib/portal-container.js'
 import { useState, useMemo } from 'react'
 import {
   Search,
@@ -801,7 +802,7 @@ export function SEOPanel({
                     <ChevronDown className="text-muted-foreground h-4 w-4" />
                   </Select.Icon>
                 </Select.Trigger>
-                <Select.Portal>
+                <Select.Portal container={adminPortalContainer()}>
                   <Select.Content className="border-border bg-card z-50 overflow-hidden rounded-lg border shadow-md">
                     <Select.Viewport className="p-1">
                       {ROBOTS_POLICY_OPTIONS.map((option) => (

package/src/components/forms/Drawer.tsx

@@ -5,6 +5,7 @@
  * token-only styling. Shared by the Forms schema / entry-detail drawers.
  */
 import * as Dialog from '@radix-ui/react-dialog'
+import { adminPortalContainer } from '../../lib/portal-container.js'
 import { X } from 'lucide-react'
 import type { ReactNode } from 'react'
 import { btnGhostIcon } from './primitives.js'
@@ -31,7 +32,7 @@ export function Drawer({
 }) {
   return (
     <Dialog.Root open={open} onOpenChange={onOpenChange}>
-      <Dialog.Portal>
+      <Dialog.Portal container={adminPortalContainer()}>
         <Dialog.Overlay className="bg-foreground/40 motion-safe:animate-in motion-safe:fade-in fixed inset-0 z-50" />
         <Dialog.Content
           {...(description ? {} : { 'aria-describedby': undefined })}

package/src/components/seo/Drawer.tsx

@@ -5,6 +5,7 @@
  * token-only styling. Shared by the SEO editor / fix / copilot drawers.
  */
 import * as Dialog from '@radix-ui/react-dialog'
+import { adminPortalContainer } from '../../lib/portal-container.js'
 import { X } from 'lucide-react'
 import type { ReactNode } from 'react'
 import { btnGhostIcon } from './primitives.js'
@@ -28,7 +29,7 @@ export function Drawer({
 }) {
   return (
     <Dialog.Root open={open} onOpenChange={onOpenChange}>
-      <Dialog.Portal>
+      <Dialog.Portal container={adminPortalContainer()}>
         <Dialog.Overlay className="bg-foreground/40 motion-safe:animate-in motion-safe:fade-in fixed inset-0 z-50" />
         <Dialog.Content
           // Radix auto-associates `aria-describedby` with the Dialog.Description

package/src/index.ts

@@ -1,6 +1,17 @@
 export { AdminRoot } from './AdminRoot.js'
 export type { AdminRootProps } from './AdminRoot.js'
 
+// Pluggable canvas renderers for custom section types (see `AdminRoot`'s
+// `sectionRenderers` prop). The types structurally mirror
+// `@actuate-media/sections-react`, so public-site renderers are assignable.
+export type {
+  AdminSectionRenderer,
+  AdminSectionRendererMap,
+  AdminSectionRendererProps,
+  AdminSectionPostContext,
+  AdminRenderImageProps,
+} from './views/page-editor/sections/index.js'
+
 export { Layout } from './layout/Layout.js'
 export type { LayoutProps } from './layout/Layout.js'
 export { Sidebar } from './layout/Sidebar.js'

package/src/layout/Header.tsx

@@ -3,6 +3,7 @@
 import { useState, type ReactNode } from 'react'
 import { Search, User, ChevronDown, Menu, Sun, Moon } from 'lucide-react'
 import * as DropdownMenu from '@radix-ui/react-dropdown-menu'
+import { adminPortalContainer } from '../lib/portal-container.js'
 import { CommandPalette } from '../components/CommandPalette.js'
 import { NotificationBell } from '../components/NotificationBell.js'
 import { useTheme } from '../components/ThemeProvider.js'
@@ -132,7 +133,7 @@ export function Header({
               </button>
             </DropdownMenu.Trigger>
 
-            <DropdownMenu.Portal>
+            <DropdownMenu.Portal container={adminPortalContainer()}>
               <DropdownMenu.Content
                 className="bg-popover text-popover-foreground border-border z-50 min-w-[200px] rounded-lg border p-1 shadow-lg"
                 align="end"

package/src/layout/Sidebar.tsx

@@ -2,6 +2,7 @@
 
 import { useEffect, useRef, useState, type ReactNode } from 'react'
 import * as DropdownMenu from '@radix-ui/react-dropdown-menu'
+import { adminPortalContainer } from '../lib/portal-container.js'
 import { useTheme } from '../components/ThemeProvider.js'
 import { fetchFormsSidebarCounts, type FormsSidebarCount } from '../lib/forms-service.js'
 import { onFormsChanged } from '../lib/forms-events.js'
@@ -664,7 +665,7 @@ function CollapsedFlyout({ item, ctx }: { item: NavItem; ctx: NavRenderContext }
         </DropdownMenu.Trigger>
       </div>
 
-      <DropdownMenu.Portal>
+      <DropdownMenu.Portal container={adminPortalContainer()}>
         <DropdownMenu.Content
           side="right"
           align="start"

package/src/lib/portal-container.ts

@@ -0,0 +1,14 @@
+/**
+ * Admin theme tokens are scoped under `.actuate-admin` (styles/theme.css),
+ * and dark mode / accent / density are applied as classes-attributes on that
+ * same root element. Radix portals default to `document.body`, which sits
+ * OUTSIDE that scope — portaled overlays would render with no theme tokens
+ * at all (transparent cards, colorless buttons) and ignore dark mode.
+ *
+ * Every Radix `*.Portal` in the admin must pass this as its `container`.
+ * Returns `undefined` during SSR (portals only materialize client-side).
+ */
+export function adminPortalContainer(): HTMLElement | undefined {
+  if (typeof document === 'undefined') return undefined
+  return document.querySelector<HTMLElement>('.actuate-admin') ?? undefined
+}

package/src/views/ApiKeys.tsx

@@ -1,6 +1,7 @@
 'use client'
 
 import * as Dialog from '@radix-ui/react-dialog'
+import { adminPortalContainer } from '../lib/portal-container.js'
 import {
   Copy,
   KeyRound,
@@ -345,7 +346,7 @@ function CreateApiKeyDialog({ open, onClose, onCreated }: CreateApiKeyDialogProp
 
   return (
     <Dialog.Root open={open} onOpenChange={(o) => !o && onClose()}>
-      <Dialog.Portal>
+      <Dialog.Portal container={adminPortalContainer()}>
         <Dialog.Overlay className="fixed inset-0 z-40 bg-black/40" />
         <Dialog.Content className="border-border bg-card fixed top-1/2 left-1/2 z-50 w-full max-w-md -translate-x-1/2 -translate-y-1/2 rounded-lg border p-6 shadow-xl">
           <Dialog.Title className="text-card-foreground mb-4 flex items-center gap-2 text-lg font-medium">
@@ -493,7 +494,7 @@ function RevealKeyDialog({
   const [shown, setShown] = useState(false)
   return (
     <Dialog.Root open onOpenChange={(o) => !o && onClose()}>
-      <Dialog.Portal>
+      <Dialog.Portal container={adminPortalContainer()}>
         <Dialog.Overlay className="fixed inset-0 z-40 bg-black/40" />
         <Dialog.Content className="border-border bg-card fixed top-1/2 left-1/2 z-50 w-full max-w-md -translate-x-1/2 -translate-y-1/2 rounded-lg border p-6 shadow-xl">
           <Dialog.Title className="text-card-foreground mb-2 flex items-center gap-2 text-lg font-medium">

package/src/views/Pages/PagesListView.tsx

@@ -14,6 +14,7 @@ import {
 } from 'lucide-react'
 import { toast } from 'sonner'
 import * as DropdownMenu from '@radix-ui/react-dropdown-menu'
+import { adminPortalContainer } from '../../lib/portal-container.js'
 import {
   applyPagesQuery,
   bulkChangePageTags,
@@ -738,7 +739,7 @@ function TagMenu({
           <ChevronDown className="h-3 w-3" aria-hidden />
         </button>
       </DropdownMenu.Trigger>
-      <DropdownMenu.Portal>
+      <DropdownMenu.Portal container={adminPortalContainer()}>
         <DropdownMenu.Content
           align="start"
           sideOffset={4}

package/src/views/Redirects.tsx

@@ -1,6 +1,7 @@
 'use client'
 
 import * as Dialog from '@radix-ui/react-dialog'
+import { adminPortalContainer } from '../lib/portal-container.js'
 import {
   Pencil,
   Plus,
@@ -278,7 +279,7 @@ export function Redirects({ onNavigate }: RedirectsProps) {
       )}
 
       <Dialog.Root open={showAddDialog} onOpenChange={setShowAddDialog}>
-        <Dialog.Portal>
+        <Dialog.Portal container={adminPortalContainer()}>
           <Dialog.Overlay className="fixed inset-0 z-50 bg-black/50" />
           <Dialog.Content className="fixed top-1/2 left-1/2 z-50 w-full max-w-md -translate-x-1/2 -translate-y-1/2 rounded-lg bg-white p-6 shadow-lg">
             <Dialog.Title className="mb-4 text-lg font-semibold text-gray-900">

package/src/views/Users.tsx

@@ -1,6 +1,7 @@
 'use client'
 
 import * as Dialog from '@radix-ui/react-dialog'
+import { adminPortalContainer } from '../lib/portal-container.js'
 import * as DropdownMenu from '@radix-ui/react-dropdown-menu'
 import {
   Users as UsersIcon,
@@ -357,7 +358,7 @@ function RoleDropdown({
           <ChevronDown size={12} aria-hidden />
         </button>
       </DropdownMenu.Trigger>
-      <DropdownMenu.Portal>
+      <DropdownMenu.Portal container={adminPortalContainer()}>
         <DropdownMenu.Content
           align="start"
           sideOffset={4}
@@ -483,7 +484,7 @@ function InviteModal({
         if (!v) reset()
       }}
     >
-      <Dialog.Portal>
+      <Dialog.Portal container={adminPortalContainer()}>
         <Dialog.Overlay className="fixed inset-0 z-50 bg-black/40 backdrop-blur-sm" />
         <Dialog.Content className="border-border bg-card fixed top-1/2 left-1/2 z-50 max-h-[90vh] w-[calc(100vw-2rem)] max-w-md -translate-x-1/2 -translate-y-1/2 overflow-y-auto rounded-lg border p-6 shadow-lg focus:outline-none">
           <div className="mb-4 flex items-center justify-between">
@@ -1187,7 +1188,7 @@ function RowActions({
           <MoreHorizontal size={16} aria-hidden />
         </button>
       </DropdownMenu.Trigger>
-      <DropdownMenu.Portal>
+      <DropdownMenu.Portal container={adminPortalContainer()}>
         <DropdownMenu.Content
           align="end"
           sideOffset={4}

package/src/views/page-builder/BlockPicker.tsx

@@ -2,6 +2,7 @@
 
 import { useState, useMemo, useRef, useEffect, useCallback } from 'react'
 import * as Dialog from '@radix-ui/react-dialog'
+import { adminPortalContainer } from '../../lib/portal-container.js'
 import {
   Star,
   Type,
@@ -126,7 +127,7 @@ export function BlockPicker({ open, onClose, onSelect }: BlockPickerProps) {
 
   return (
     <Dialog.Root open={open} onOpenChange={(isOpen) => !isOpen && onClose()}>
-      <Dialog.Portal>
+      <Dialog.Portal container={adminPortalContainer()}>
         <Dialog.Overlay className="motion-safe:animate-in motion-safe:fade-in-0 fixed inset-0 z-50 bg-black/50" />
         <Dialog.Content
           className="bg-card border-border fixed top-1/2 left-1/2 z-50 flex max-h-[80vh] w-full max-w-2xl -translate-x-1/2 -translate-y-1/2 flex-col overflow-hidden rounded-xl border shadow-2xl"

package/src/views/page-editor/PageSectionEditor.tsx

@@ -33,7 +33,7 @@ import {
 } from '../../lib/preview-link.js'
 import type { SectionSettings, SectionTypeId } from './section-types.js'
 import { DEFAULT_VIEWPORT, type ViewportId } from './viewports.js'
-import { hasCanvasRenderer } from './sections/index.js'
+import { hasCanvasRenderer, useAdminSectionRenderers } from './sections/index.js'
 import { EditorTopBar, type SaveState } from './EditorTopBar.js'
 import { SectionsPanel } from './SectionsPanel.js'
 import { EditorCanvas } from './EditorCanvas.js'
@@ -91,6 +91,7 @@ export function PageSectionEditor({
   const [validation, setValidation] = useState<ValidationResult | null>(null)
 
   const { canEdit, canPublish } = useMemo(() => deriveCan(session), [session])
+  const customRenderers = useAdminSectionRenderers()
 
   // A misconfigured `pages` collection (missing the fields the editor
   // writes) would silently drop content on save — detect it up front.
@@ -418,12 +419,15 @@ export function PageSectionEditor({
     new Set(page.sections.filter((s) => s.unmanaged).map((s) => s.sectionType)),
   )
 
-  // Section types the canvas renders as placeholders (custom + unmanaged).
-  // When present the editor surfaces "structure view" messaging and promotes
-  // "View on site" as the primary design preview.
+  // Section types the canvas renders as placeholders — no built-in body
+  // component and no consumer-registered admin renderer. When present the
+  // editor surfaces "structure view" messaging and promotes "View on site"
+  // as the primary design preview.
   const structuralTypes = Array.from(
     new Set(
-      page.sections.filter((s) => !hasCanvasRenderer(s.sectionType)).map((s) => s.sectionType),
+      page.sections
+        .filter((s) => !hasCanvasRenderer(s.sectionType) && !customRenderers[s.sectionType])
+        .map((s) => s.sectionType),
     ),
   )
 

package/src/views/page-editor/SectionsPanel.tsx

@@ -28,6 +28,7 @@ import {
 } from '@dnd-kit/sortable'
 import { CSS } from '@dnd-kit/utilities'
 import * as DropdownMenu from '@radix-ui/react-dropdown-menu'
+import { adminPortalContainer } from '../../lib/portal-container.js'
 import type { PageSection } from '../../lib/page-editor-service.js'
 import { sectionIconFor } from './section-icons.js'
 
@@ -238,7 +239,7 @@ function SortableSectionItem({
                   <MoreVertical className="h-4 w-4" aria-hidden />
                 </button>
               </DropdownMenu.Trigger>
-              <DropdownMenu.Portal>
+              <DropdownMenu.Portal container={adminPortalContainer()}>
                 <DropdownMenu.Content
                   align="end"
                   sideOffset={4}

package/src/views/page-editor/sections/SectionRenderer.tsx

@@ -2,7 +2,9 @@
 
 import { Puzzle } from 'lucide-react'
 import type { PageSection } from '../../../lib/page-editor-service.js'
+import { ErrorBoundary } from '../../../components/ErrorBoundary.js'
 import { getSectionType } from '../section-types.js'
+import { ADMIN_RENDER_OPTIONS, useAdminSectionRenderers } from './admin-renderers.js'
 import { backgroundClass, paddingClass, type PostRenderContext } from './parts.js'
 import { HeroBannerSection } from './HeroBannerSection.js'
 import { MissionSection } from './MissionSection.js'
@@ -41,6 +43,8 @@ export function hasCanvasRenderer(sectionType: string): boolean {
 
 /** Dispatch a section's body component by type. Shared by editor + preview. */
 function SectionBody({ section, context }: { section: PageSection; context?: PostRenderContext }) {
+  const customRenderers = useAdminSectionRenderers()
+
   switch (section.sectionType) {
     case 'hero':
       return <HeroBannerSection section={section} />
@@ -62,11 +66,33 @@ function SectionBody({ section, context }: { section: PageSection; context?: Pos
       return <RelatedPostsSection section={section} context={context} />
     case 'gallery':
       return <GallerySection section={section} />
-    default:
-      // Custom (config-declared) types and unmanaged (externally-managed)
-      // sections have no built-in body component. Render a neutral placeholder
-      // so the canvas reflects their presence + order instead of a blank gap.
+    default: {
+      // Custom (config-declared) and unmanaged types: use a consumer-supplied
+      // canvas renderer when one is registered (see admin-renderers.tsx).
+      // Consumer code can throw, so a per-section error boundary falls back
+      // to the structural placeholder instead of taking down the editor.
+      const Custom = customRenderers[section.sectionType]
+      if (Custom) {
+        // The renderer contract types `settings` as an open record (matching
+        // the sections-react wire shape); the admin's concrete
+        // `SectionSettings` interface is the same object at runtime but has
+        // no index signature, so bridge the nominal gap here.
+        const wireSection = {
+          ...section,
+          settings: { ...section.settings } as Record<string, unknown>,
+        }
+        // Rendered as a component (not invoked inline) so a throw happens
+        // inside the boundary's subtree and is actually caught.
+        return (
+          <ErrorBoundary key={section.id} fallback={<PlaceholderSection section={section} />}>
+            <Custom section={wireSection} ctx={context} options={ADMIN_RENDER_OPTIONS} />
+          </ErrorBoundary>
+        )
+      }
+      // No renderer registered: a neutral placeholder keeps the canvas
+      // reflecting the section's presence + order instead of a blank gap.
       return <PlaceholderSection section={section} />
+    }
   }
 }
 

package/src/views/page-editor/sections/admin-renderers.tsx

@@ -0,0 +1,105 @@
+'use client'
+
+/**
+ * Pluggable canvas renderers for custom section types.
+ *
+ * By default the editor canvas renders custom (config-declared) and unmanaged
+ * section types as structural placeholders. Projects that want a real design
+ * preview inside the admin can pass renderers to `<AdminRoot
+ * sectionRenderers={...}>`; the canvas and the eye preview then use them in
+ * place of the placeholder.
+ *
+ * The renderer signature is a structural mirror of `SectionRenderer` from
+ * `@actuate-media/sections-react` (cms-admin depends on cms-core only, so the
+ * type is duplicated rather than imported). Because the shapes match, a
+ * consumer can hand `AdminRoot` the exact same components it registers for
+ * the public site:
+ *
+ * ```tsx
+ * import { OPAL_RENDERERS } from './sections' // SectionRendererMap
+ * <AdminRoot sectionRenderers={OPAL_RENDERERS} ... />
+ * ```
+ *
+ * Renderers run inside the admin bundle, so they must be client-safe (no
+ * server-only imports). Each one is wrapped in an error boundary — a throwing
+ * renderer falls back to the structural placeholder instead of taking down
+ * the editor.
+ */
+import { createContext, useContext, type ReactNode } from 'react'
+
+/** Structural mirror of `RenderImageProps` from `@actuate-media/sections-react`. */
+export interface AdminRenderImageProps {
+  src: string
+  alt: string
+  width?: number | null
+  height?: number | null
+  className?: string
+  priority?: boolean
+  sizes?: string
+}
+
+/** Structural mirror of `PostContext` from `@actuate-media/sections-react`. */
+export interface AdminSectionPostContext {
+  title?: string
+  excerpt?: string
+  body?: string
+  featuredImageUrl?: string
+  publishDate?: string | null
+  category?: string
+  author?: { name?: string; bio?: string; avatarUrl?: string }
+  relatedPosts?: Array<{ title: string; url?: string; excerpt?: string }>
+}
+
+/** Props passed to an admin section renderer (mirrors `SectionRendererProps`). */
+export interface AdminSectionRendererProps {
+  section: {
+    id: string
+    sectionType: string
+    name?: string
+    visible?: boolean
+    content?: Record<string, unknown>
+    settings?: Record<string, unknown>
+  }
+  ctx?: AdminSectionPostContext
+  options: {
+    sanitizeHtml: (html: string) => string
+    baseUrl: string
+    renderImage: (props: AdminRenderImageProps) => ReactNode
+  }
+}
+
+/** A canvas renderer for one custom section type. */
+export type AdminSectionRenderer = (props: AdminSectionRendererProps) => ReactNode
+
+/** Section-type id → canvas renderer. */
+export type AdminSectionRendererMap = Record<string, AdminSectionRenderer>
+
+/**
+ * Render options passed to every admin renderer. Rich text is sanitized on
+ * write by cms-core, so the canvas (same trust domain as the public default)
+ * uses the identity sanitizer; images render as plain lazy `<img>` since the
+ * editor canvas has no next/image pipeline.
+ */
+export const ADMIN_RENDER_OPTIONS: AdminSectionRendererProps['options'] = {
+  sanitizeHtml: (html) => html,
+  baseUrl: '',
+  renderImage: ({ src, alt, className, priority, width, height }) => (
+    <img
+      src={src}
+      alt={alt}
+      className={className}
+      width={width ?? undefined}
+      height={height ?? undefined}
+      loading={priority ? undefined : 'lazy'}
+    />
+  ),
+}
+
+const AdminSectionRenderersContext = createContext<AdminSectionRendererMap>({})
+
+export const AdminSectionRenderersProvider = AdminSectionRenderersContext.Provider
+
+/** The renderer map passed to `<AdminRoot sectionRenderers>` (empty by default). */
+export function useAdminSectionRenderers(): AdminSectionRendererMap {
+  return useContext(AdminSectionRenderersContext)
+}

package/src/views/page-editor/sections/index.ts

@@ -1,5 +1,17 @@
 export { SectionRenderer, hasCanvasRenderer } from './SectionRenderer.js'
 export type { SectionRendererProps } from './SectionRenderer.js'
+export {
+  AdminSectionRenderersProvider,
+  useAdminSectionRenderers,
+  ADMIN_RENDER_OPTIONS,
+} from './admin-renderers.js'
+export type {
+  AdminSectionRenderer,
+  AdminSectionRendererMap,
+  AdminSectionRendererProps,
+  AdminSectionPostContext,
+  AdminRenderImageProps,
+} from './admin-renderers.js'
 export type { PostRenderContext } from './parts.js'
 export { HeroBannerSection } from './HeroBannerSection.js'
 export { MissionSection } from './MissionSection.js'

package/src/views/post-editor/PostSectionEditor.tsx

@@ -34,7 +34,11 @@ import {
   resolveSiteUrl,
 } from '../../lib/preview-link.js'
 import type { SectionSettings, SectionTypeId } from '../page-editor/section-types.js'
-import { hasCanvasRenderer, type PostRenderContext } from '../page-editor/sections/index.js'
+import {
+  hasCanvasRenderer,
+  useAdminSectionRenderers,
+  type PostRenderContext,
+} from '../page-editor/sections/index.js'
 import { DEFAULT_VIEWPORT, type ViewportId } from '../page-editor/viewports.js'
 import { EditorTopBar, type SaveState } from '../page-editor/EditorTopBar.js'
 import { SectionsPanel } from '../page-editor/SectionsPanel.js'
@@ -112,6 +116,7 @@ export function PostSectionEditor({
   const [validation, setValidation] = useState<ValidationResult | null>(null)
 
   const { canEdit, canPublish } = useMemo(() => deriveCan(session), [session])
+  const customRenderers = useAdminSectionRenderers()
 
   const typeLabel = useMemo(() => {
     const col = config?.collections?.[postType]
@@ -419,12 +424,15 @@ export function PostSectionEditor({
 
   const selected = post.sections.find((s) => s.id === selectedId) ?? null
 
-  // Section types the canvas renders as placeholders (custom + unmanaged).
-  // When present the editor surfaces "structure view" messaging and promotes
-  // "View on site" as the primary design preview.
+  // Section types the canvas renders as placeholders — no built-in body
+  // component and no consumer-registered admin renderer. When present the
+  // editor surfaces "structure view" messaging and promotes "View on site"
+  // as the primary design preview.
   const structuralTypes = Array.from(
     new Set(
-      post.sections.filter((s) => !hasCanvasRenderer(s.sectionType)).map((s) => s.sectionType),
+      post.sections
+        .filter((s) => !hasCanvasRenderer(s.sectionType) && !customRenderers[s.sectionType])
+        .map((s) => s.sectionType),
     ),
   )
 

package/src/views/settings/components.tsx

@@ -3,6 +3,7 @@
 import * as Dialog from '@radix-ui/react-dialog'
 import { AlertTriangle, Check, Loader2, Lock } from 'lucide-react'
 import { useId, type ReactNode } from 'react'
+import { adminPortalContainer } from '../../lib/portal-container.js'
 import type { SettingsSourceMetadata, ValidationIssue } from './useGeneralSettings.js'
 
 /**
@@ -290,7 +291,7 @@ export function ConfirmDangerousSettingDialog({
 }) {
   return (
     <Dialog.Root open={open} onOpenChange={(o) => !o && onCancel()}>
-      <Dialog.Portal>
+      <Dialog.Portal container={adminPortalContainer()}>
         <Dialog.Overlay className="fixed inset-0 z-50 bg-black/50" />
         <Dialog.Content className="bg-card text-card-foreground fixed top-1/2 left-1/2 z-50 w-full max-w-md -translate-x-1/2 -translate-y-1/2 rounded-lg p-6 shadow-lg">
           <div className="mb-3 flex items-center gap-2">