@actuate-media/cms-admin 0.38.0 → 0.39.0

package/src/AdminRoot.tsx

@@ -5,6 +5,10 @@ import { toast } from 'sonner'
 import { Layout } from './layout/Layout.js'
 import { useAdminRouter } from './router/index.js'
 import { cmsApi, ensureCsrfToken } from './lib/api.js'
+import {
+  registerSectionTypes,
+  resetCustomSectionTypes,
+} from '@actuate-media/cms-core/page-sections'
 import { Dashboard } from './views/Dashboard.js'
 import { CollectionList } from './views/CollectionList.js'
 import { DocumentEdit } from './views/DocumentEdit.js'
@@ -155,6 +159,14 @@ function AdminShell({
     }
   }, [session])
 
+  // Register config-declared custom section types into the client registry so
+  // the Page/Post editors recognize them (Add Section gallery + field-driven
+  // inspector). Reset first so a config change never leaves stale types.
+  useEffect(() => {
+    resetCustomSectionTypes()
+    registerSectionTypes(config?.sections?.customTypes)
+  }, [config])
+
   const shortcuts = useMemo(
     () => ({
       'mod+k': () => {

package/src/__tests__/components/breadcrumbs-is-id.test.ts

@@ -0,0 +1,32 @@
+import { describe, expect, it } from 'vitest'
+
+import { isId } from '../../components/Breadcrumbs.js'
+
+/**
+ * `isId` decides whether a path segment is a document id (shown as "Edit ...")
+ * versus a human-readable route segment (title-cased). Prisma uses
+ * `@default(cuid())`, so the regression here is CUIDs being mistaken for slugs
+ * and rendered raw in the breadcrumb trail.
+ */
+describe('Breadcrumbs.isId', () => {
+  it('recognizes cuid ids (Prisma @default(cuid()))', () => {
+    expect(isId('clp1q2w3e4r5t6y7u8i9o0p1a')).toBe(true)
+    expect(isId('cm5xk3a9b0001qz8f4g7h2j6k')).toBe(true)
+  })
+
+  it('recognizes cuid2 / long base36 token ids', () => {
+    expect(isId('tz4a8f5d2e9b1c6h3k7m0p2q')).toBe(true)
+  })
+
+  it('still recognizes numeric and hex ids', () => {
+    expect(isId('12345')).toBe(true)
+    expect(isId('a1b2c3d4e5f6')).toBe(true)
+  })
+
+  it('does not treat human-readable slugs as ids', () => {
+    expect(isId('about')).toBe(false)
+    expect(isId('contact-us')).toBe(false)
+    expect(isId('new')).toBe(false)
+    expect(isId('page-builder')).toBe(false)
+  })
+})

package/src/__tests__/lib/page-editor-service-api.test.ts

@@ -141,6 +141,49 @@ describe('savePageDraft', () => {
     cmsApi.mockResolvedValue({ error: 'Forbidden', status: 403 })
     await expect(savePageDraft(draft('p1'))).rejects.toThrow('Forbidden')
   })
+
+  it('round-trips externally-managed (unmanaged) sections on save without data loss', async () => {
+    // Load a page that carries an unknown section type (seed/code-owned).
+    cmsApi.mockResolvedValueOnce({
+      data: {
+        id: 'p9',
+        title: 'Landing',
+        slug: 'landing',
+        status: 'DRAFT',
+        data: {
+          path: '/landing',
+          sections: [
+            { id: 's1', sectionType: 'hero', content: { heading: 'Hi' } },
+            { id: 's2', sectionType: 'opal-hero', content: { title: 'Custom', cta: '/x' } },
+          ],
+        },
+      },
+      status: 200,
+    })
+    const page = await fetchPageForEditor('p9')
+    expect(page.sections.find((s) => s.id === 's2')?.unmanaged).toBe(true)
+
+    cmsApi.mockResolvedValueOnce({
+      data: {
+        id: 'p9',
+        title: 'Landing',
+        slug: 'landing',
+        status: 'DRAFT',
+        data: { sections: [] },
+      },
+      status: 200,
+    })
+    await savePageDraft(page)
+
+    const [, opts] = cmsApi.mock.calls[1] as [string, RequestInit]
+    const body = JSON.parse(opts.body as string)
+    const opal = body.sections.find((s: { sectionType: string }) => s.sectionType === 'opal-hero')
+    // The unknown section survives the save, content intact...
+    expect(opal).toBeTruthy()
+    expect(opal.content).toEqual({ title: 'Custom', cta: '/x' })
+    // ...but the derived `unmanaged` marker is never persisted.
+    expect('unmanaged' in opal).toBe(false)
+  })
 })
 
 describe('publishPage', () => {

package/src/__tests__/no-server-barrel-imports.test.ts

@@ -0,0 +1,58 @@
+import { readdirSync, readFileSync, statSync } from 'node:fs'
+import { join, relative } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { describe, expect, it } from 'vitest'
+
+// The cms-core main barrel (`@actuate-media/cms-core`) re-exports server-only
+// code (getDB, pg, sharp, graphql, codegen). Importing a runtime *value* from
+// it inside cms-admin drags that server graph into the client admin bundle —
+// the bug Opal hit where Turbopack pulled `pg`/`fs` into the browser build.
+//
+// Type-only imports (`import type` / `export type`) are erased by tsc and are
+// safe. Page-builder runtime utilities must come from the client-safe
+// `@actuate-media/cms-core/page-builder` subpath instead. This test fails if
+// any source file reintroduces a value import from the bare barrel.
+
+const SRC_DIR = fileURLToPath(new URL('../', import.meta.url))
+
+function collectSourceFiles(dir: string, acc: string[] = []): string[] {
+  for (const entry of readdirSync(dir)) {
+    const full = join(dir, entry)
+    if (statSync(full).isDirectory()) {
+      if (entry === '__tests__' || entry === 'node_modules' || entry === 'dist') continue
+      collectSourceFiles(full, acc)
+    } else if (/\.(ts|tsx)$/.test(entry)) {
+      acc.push(full)
+    }
+  }
+  return acc
+}
+
+// Matches `import ... from '@actuate-media/cms-core'` and the `export ... from`
+// form, capturing whether the `type` modifier follows the keyword. The import
+// clause is restricted to a brace block / namespace / default binding so the
+// match can't span across adjacent statements. The closing quote immediately
+// after `cms-core` excludes subpath imports like `.../page-builder`.
+const BARE_BARREL =
+  /\b(import|export)\s+(type\s+)?(?:\{[^}]*\}|\*\s+as\s+[A-Za-z_$][\w$]*|[A-Za-z_$][\w$]*(?:\s*,\s*\{[^}]*\})?)\s+from\s+['"]@actuate-media\/cms-core['"]/g
+
+describe('cms-admin client/server bundle boundary', () => {
+  it('never imports runtime values from the bare @actuate-media/cms-core barrel', () => {
+    const offenders: string[] = []
+
+    for (const file of collectSourceFiles(SRC_DIR)) {
+      const content = readFileSync(file, 'utf-8')
+      for (const match of content.matchAll(BARE_BARREL)) {
+        const isTypeOnly = Boolean(match[2])
+        if (!isTypeOnly) {
+          offenders.push(`${relative(SRC_DIR, file)}: ${match[0].replace(/\s+/g, ' ').trim()}`)
+        }
+      }
+    }
+
+    expect(
+      offenders,
+      `Use '@actuate-media/cms-core/page-builder' (or 'import type') instead:\n${offenders.join('\n')}`,
+    ).toEqual([])
+  })
+})

package/src/__tests__/router/navigate-pushstate.test.ts

@@ -0,0 +1,46 @@
+// @vitest-environment happy-dom
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import { act, renderHook } from '@testing-library/react'
+
+import { useAdminRouter } from '../../router/index.js'
+
+// Next.js 16 patches `history.pushState` and only short-circuits to the native
+// implementation when the state object carries `__NA` (or `_N`). Without that
+// marker it runs URL parsing that throws "Invalid URL" for the admin SPA. These
+// tests pin the marker so the Next 16 admin routing regression can't reappear.
+describe('useAdminRouter navigate', () => {
+  let pushStateSpy: ReturnType<typeof vi.spyOn>
+
+  beforeEach(() => {
+    pushStateSpy = vi.spyOn(window.history, 'pushState')
+  })
+
+  afterEach(() => {
+    pushStateSpy.mockRestore()
+  })
+
+  it('marks pushState state with __NA so Next.js 16 leaves it untouched', () => {
+    const { result } = renderHook(() => useAdminRouter('/admin', '/'))
+
+    act(() => {
+      result.current.navigate('/collections/posts')
+    })
+
+    expect(pushStateSpy).toHaveBeenCalledTimes(1)
+    const [state, , url] = pushStateSpy.mock.calls[0]!
+    expect(state).toMatchObject({ adminPath: '/collections/posts', __NA: true })
+    expect(url).toBe('/admin/collections/posts')
+  })
+
+  it('uses the bare basePath (with __NA) when navigating to root', () => {
+    const { result } = renderHook(() => useAdminRouter('/securelogin', '/'))
+
+    act(() => {
+      result.current.navigate('/')
+    })
+
+    const [state, , url] = pushStateSpy.mock.calls[0]!
+    expect(state).toMatchObject({ adminPath: '/', __NA: true })
+    expect(url).toBe('/securelogin')
+  })
+})

package/src/__tests__/views/appearance-settings.render.test.tsx

@@ -17,6 +17,24 @@ const cmsApi = vi.fn(async (endpoint: string, options?: { method?: string; body?
       data: { id: 'new-logo', url: 'https://cdn.example.com/x.svg', mimeType: 'image/svg+xml' },
       status: 200,
     }
+  if (endpoint.startsWith('/media?') && method === 'GET')
+    return {
+      data: {
+        items: [
+          {
+            id: 'existing-logo',
+            filename: 'existing.png',
+            storageKey: 'https://cdn.example.com/existing.png',
+            url: 'https://cdn.example.com/existing.png',
+            mimeType: 'image/png',
+            fileSize: 1234,
+            width: 400,
+            height: 100,
+          },
+        ],
+      },
+      status: 200,
+    }
   return { data: {}, status: 200 }
 })
 
@@ -120,6 +138,33 @@ describe('AppearanceTab', () => {
     )
   })
 
+  it('references an existing media-library asset without re-uploading', async () => {
+    render(<AppearanceTab role="ADMIN" />)
+    await screen.findByText('Branding')
+
+    fireEvent.click(screen.getByRole('button', { name: /choose primary logo from media library/i }))
+
+    const thumb = await screen.findByRole('button', { name: /existing\.png/i })
+    fireEvent.click(thumb)
+
+    // No upload should be issued — we reference the existing asset by id.
+    expect(cmsApi.mock.calls.some(([endpoint]) => endpoint === '/media/upload')).toBe(false)
+
+    const save = await screen.findByRole('button', { name: 'Save Changes' })
+    await waitFor(() => expect((save as HTMLButtonElement).disabled).toBe(false))
+    fireEvent.click(save)
+
+    await waitFor(() =>
+      expect(cmsApi).toHaveBeenCalledWith(
+        '/globals/settings',
+        expect.objectContaining({
+          method: 'PUT',
+          body: expect.stringContaining('"publicPrimaryLogoAssetId":"existing-logo"'),
+        }),
+      ),
+    )
+  })
+
   it('is read-only for non-admins', async () => {
     render(<AppearanceTab role="EDITOR" />)
 

package/src/components/Breadcrumbs.tsx

@@ -27,8 +27,17 @@ function labelFor(segment: string): string {
   )
 }
 
-function isId(segment: string): boolean {
-  return /^\d+$/.test(segment) || /^[0-9a-f]{8,}$/i.test(segment)
+export function isId(segment: string): boolean {
+  return (
+    // numeric id
+    /^\d+$/.test(segment) ||
+    // hex id (e.g. ObjectId / md5-style)
+    /^[0-9a-f]{8,}$/i.test(segment) ||
+    // cuid (Prisma's @default(cuid())): leading "c" + base36, ~25 chars
+    /^c[a-z0-9]{20,}$/i.test(segment) ||
+    // cuid2 / other long base36 token ids (24+ chars, no separators)
+    /^[a-z0-9]{24,}$/i.test(segment)
+  )
 }
 
 export interface BreadcrumbsProps {

package/src/components/MediaPickerModal.tsx

@@ -10,6 +10,8 @@ interface MediaItem {
   id: string
   filename: string
   storageKey: string
+  /** Normalized public URL from the media list endpoint (preferred for display). */
+  url?: string
   mimeType: string
   fileSize: number
   width?: number
@@ -20,6 +22,8 @@ interface MediaItem {
 export interface SelectedMediaItem {
   id: string
   storageKey: string
+  /** Normalized public URL (falls back to storageKey when absent). */
+  url: string
   filename: string
   mimeType: string
   width?: number
@@ -36,6 +40,12 @@ export interface MediaPickerModalProps {
    */
   onSelectItem?: (item: SelectedMediaItem) => void
   accept?: string
+  /**
+   * Hide the "Upload New" tab and show only the existing library. Used where a
+   * caller has its own upload path (e.g. brand assets, which upload with
+   * format-preserving options) but still wants to reuse library assets.
+   */
+  libraryOnly?: boolean
 }
 
 export function MediaPickerModal({
@@ -44,6 +54,7 @@ export function MediaPickerModal({
   onSelect,
   onSelectItem,
   accept,
+  libraryOnly = false,
 }: MediaPickerModalProps) {
   const [tab, setTab] = useState<'library' | 'upload'>('library')
   const [search, setSearch] = useState('')
@@ -74,11 +85,12 @@ export function MediaPickerModal({
       toast.error(res.error)
     } else if (res.data) {
       const mediaItem = res.data as MediaItem
-      const url = mediaItem.storageKey ?? ''
+      const url = mediaItem.url || mediaItem.storageKey || ''
       toast.success(`Uploaded ${file.name}`)
       onSelectItem?.({
         id: mediaItem.id,
         storageKey: mediaItem.storageKey,
+        url,
         filename: mediaItem.filename ?? file.name,
         mimeType: mediaItem.mimeType ?? file.type,
         width: mediaItem.width,
@@ -93,15 +105,17 @@ export function MediaPickerModal({
   }
 
   function handleSelectItem(item: MediaItem) {
+    const url = item.url || item.storageKey || ''
     onSelectItem?.({
       id: item.id,
       storageKey: item.storageKey,
+      url,
       filename: item.filename,
       mimeType: item.mimeType,
       width: item.width,
       height: item.height,
     })
-    onSelect(item.storageKey, item.filename)
+    onSelect(url, item.filename)
     onClose()
   }
 
@@ -121,31 +135,33 @@ export function MediaPickerModal({
           </button>
         </div>
 
-        <div className="flex border-b border-gray-200">
-          <button
-            onClick={() => setTab('library')}
-            className={`flex-1 px-4 py-2.5 text-sm font-medium transition-colors ${
-              tab === 'library'
-                ? 'border-b-2 border-blue-600 text-blue-600'
-                : 'text-gray-500 hover:text-gray-700'
-            }`}
-          >
-            Media Library
-          </button>
-          <button
-            onClick={() => setTab('upload')}
-            className={`flex-1 px-4 py-2.5 text-sm font-medium transition-colors ${
-              tab === 'upload'
-                ? 'border-b-2 border-blue-600 text-blue-600'
-                : 'text-gray-500 hover:text-gray-700'
-            }`}
-          >
-            Upload New
-          </button>
-        </div>
+        {!libraryOnly && (
+          <div className="flex border-b border-gray-200">
+            <button
+              onClick={() => setTab('library')}
+              className={`flex-1 px-4 py-2.5 text-sm font-medium transition-colors ${
+                tab === 'library'
+                  ? 'border-b-2 border-blue-600 text-blue-600'
+                  : 'text-gray-500 hover:text-gray-700'
+              }`}
+            >
+              Media Library
+            </button>
+            <button
+              onClick={() => setTab('upload')}
+              className={`flex-1 px-4 py-2.5 text-sm font-medium transition-colors ${
+                tab === 'upload'
+                  ? 'border-b-2 border-blue-600 text-blue-600'
+                  : 'text-gray-500 hover:text-gray-700'
+              }`}
+            >
+              Upload New
+            </button>
+          </div>
+        )}
 
         <div className="flex-1 overflow-y-auto p-4">
-          {tab === 'library' ? (
+          {libraryOnly || tab === 'library' ? (
             <>
               <div className="relative mb-4">
                 <Search className="absolute top-1/2 left-3 h-4 w-4 -translate-y-1/2 text-gray-400" />
@@ -168,20 +184,33 @@ export function MediaPickerModal({
                 </div>
               ) : (
                 <div className="grid grid-cols-3 gap-3 sm:grid-cols-4">
-                  {imageItems.map((item: MediaItem) => (
-                    <button
-                      key={item.id}
-                      onClick={() => handleSelectItem(item)}
-                      className="group relative aspect-square overflow-hidden rounded-lg border-2 border-gray-200 bg-gray-100 transition-colors hover:border-blue-500"
-                    >
-                      <div className="flex h-full w-full items-center justify-center">
-                        <ImageIcon className="h-8 w-8 text-gray-300" />
-                      </div>
-                      <div className="absolute inset-x-0 bottom-0 bg-black/60 p-1.5 opacity-0 transition-opacity group-hover:opacity-100">
-                        <p className="truncate text-xs text-white">{item.filename}</p>
-                      </div>
-                    </button>
-                  ))}
+                  {imageItems.map((item: MediaItem) => {
+                    const src = item.url || item.storageKey
+                    return (
+                      <button
+                        key={item.id}
+                        onClick={() => handleSelectItem(item)}
+                        title={item.filename}
+                        className="group relative aspect-square overflow-hidden rounded-lg border-2 border-gray-200 bg-gray-100 transition-colors hover:border-blue-500"
+                      >
+                        {src ? (
+                          <img
+                            src={src}
+                            alt={item.filename}
+                            loading="lazy"
+                            className="h-full w-full object-contain"
+                          />
+                        ) : (
+                          <div className="flex h-full w-full items-center justify-center">
+                            <ImageIcon className="h-8 w-8 text-gray-300" />
+                          </div>
+                        )}
+                        <div className="absolute inset-x-0 bottom-0 bg-black/60 p-1.5 opacity-0 transition-opacity group-hover:opacity-100">
+                          <p className="truncate text-xs text-white">{item.filename}</p>
+                        </div>
+                      </button>
+                    )
+                  })}
                 </div>
               )}
             </>

package/src/hooks/useBuilderState.ts

@@ -23,7 +23,7 @@ import {
   createColumn,
   createBlock,
   hasChildren,
-} from '@actuate-media/cms-core'
+} from '@actuate-media/cms-core/page-builder'
 
 export type DeviceMode = 'desktop' | 'tablet' | 'mobile'
 export type PanelTab = 'block' | 'node' | 'page' | 'seo' | 'design'

package/src/lib/page-editor-service.ts

@@ -112,7 +112,9 @@ export function validatePage(page: EditorPage, forPublish = false): ValidationRe
       errors.push('Add at least one visible section before publishing.')
     }
 
-    for (const section of visible) {
+    // Unmanaged (externally-managed) sections have no registered field schema,
+    // so they can't be content-validated here and must not block publish.
+    for (const section of visible.filter((s) => !s.unmanaged)) {
       const def = getSectionType(section.sectionType)
       const label = section.name || def?.name || 'Section'
       const result = validateSectionContent(section.sectionType, section.content, section.settings)
@@ -216,7 +218,9 @@ function rowToEditorPage(doc: DocumentApiRow): EditorPage {
     slug,
     path: typeof data.path === 'string' && data.path ? data.path : slug ? `/${slug}` : '/',
     status: doc.status ?? 'DRAFT',
-    sections: coerceSectionsCore(data.sections),
+    // Preserve unknown (externally-managed) sections so the editor can show
+    // them read-only and round-trip them on save instead of dropping them.
+    sections: coerceSectionsCore(data.sections, { preserveUnknown: true }),
     seoTitle: typeof data.metaTitle === 'string' ? data.metaTitle : '',
     seoDescription: typeof data.metaDescription === 'string' ? data.metaDescription : '',
     publishedAt: doc.publishedAt ?? null,
@@ -252,7 +256,10 @@ function toWriteBody(page: EditorPage, extra?: Record<string, unknown>): string
     title: page.title,
     slug: page.slug,
     path: page.path,
-    sections: page.sections,
+    // Unmanaged sections are part of `page.sections`, so they round-trip on
+    // every save (no data loss). Strip the derived `unmanaged` marker — it is
+    // recomputed from the registry on read, so persisting it would only stale.
+    sections: page.sections.map(({ unmanaged: _unmanaged, ...rest }) => rest),
     metaTitle: page.seoTitle,
     metaDescription: page.seoDescription,
     ...extra,

package/src/router/index.ts

@@ -41,7 +41,12 @@ export function useAdminRouter(basePath = '/admin', serverPath = '/') {
     setCurrentPath(normalizedPath)
 
     const fullUrl = normalizedPath === '/' ? baseRef.current : `${baseRef.current}${normalizedPath}`
-    window.history.pushState({ adminPath: normalizedPath }, '', fullUrl)
+    // `__NA: true` marks this as a native history entry so Next.js 16's patched
+    // `history.pushState` short-circuits to the original implementation instead
+    // of running its URL-parsing path (which throws "Invalid URL"). The admin is
+    // a self-contained SPA with its own `popstate` listener, so we deliberately
+    // bypass Next's router/RSC sync on in-admin navigation.
+    window.history.pushState({ adminPath: normalizedPath, __NA: true }, '', fullUrl)
   }, [])
 
   // Build an absolute (basePath-prefixed) admin URL without navigating. Used

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

@@ -4,7 +4,7 @@ import { useState, useMemo, useCallback } from 'react'
 import { Star, Copy, Trash2 } from 'lucide-react'
 import * as SwitchPrimitive from '@radix-ui/react-switch'
 import type { BlockNode, BlockTypeDefinition, FieldDefinition } from '@actuate-media/cms-core'
-import { BlockCatalog } from '@actuate-media/cms-core'
+import { BlockCatalog } from '@actuate-media/cms-core/page-builder'
 import { AIBlockAssist } from './AIBlockAssist.js'
 import { RelationshipField } from './RelationshipField.js'
 import { TipTapEditor } from '../../components/TipTapEditor.js'

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

@@ -20,7 +20,7 @@ import {
   Check,
 } from 'lucide-react'
 import type { LucideIcon } from 'lucide-react'
-import { BlockCatalog } from '@actuate-media/cms-core'
+import { BlockCatalog } from '@actuate-media/cms-core/page-builder'
 import type { BlockTypeDefinition, VariantDefinition } from '@actuate-media/cms-core'
 
 export interface BlockPickerProps {

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

@@ -1,7 +1,7 @@
 'use client'
 
 import { useState, useMemo } from 'react'
-import { analyzeDesign } from '@actuate-media/cms-core'
+import { analyzeDesign } from '@actuate-media/cms-core/page-builder'
 import type {
   PageNode,
   DesignAnalysis,

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

@@ -1,7 +1,7 @@
 'use client'
 
 import { useState, useMemo } from 'react'
-import { analyzeSEO } from '@actuate-media/cms-core'
+import { analyzeSEO } from '@actuate-media/cms-core/page-builder'
 import type {
   PageNode,
   BuilderSEOAnalysis,

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

@@ -15,7 +15,12 @@ import {
 } from 'lucide-react'
 import { toast } from 'sonner'
 import { cmsApi } from '../../lib/api.js'
-import { createSection, createContainer, createRow, createColumn } from '@actuate-media/cms-core'
+import {
+  createSection,
+  createContainer,
+  createRow,
+  createColumn,
+} from '@actuate-media/cms-core/page-builder'
 
 export interface SavedSectionsProps {
   onNavigate: (path: string) => void

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

@@ -14,7 +14,7 @@ import {
 } from 'lucide-react'
 import type { LucideIcon } from 'lucide-react'
 import { cmsApi } from '../../lib/api.js'
-import { createEmptyPage } from '@actuate-media/cms-core'
+import { createEmptyPage } from '@actuate-media/cms-core/page-builder'
 import type { PageNode } from '@actuate-media/cms-core'
 
 export interface TemplatePickerProps {

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

@@ -1,7 +1,7 @@
 'use client'
 
 import { useCallback, useEffect, useMemo, useState } from 'react'
-import { AlertTriangle, Blocks, Loader2 } from 'lucide-react'
+import { AlertTriangle, Blocks, Loader2, Lock } from 'lucide-react'
 import { toast } from 'sonner'
 import { ConfirmDialog } from '../../components/ui/ConfirmDialog.js'
 import { ErrorBoundary } from '../../components/ErrorBoundary.js'
@@ -392,6 +392,12 @@ export function PageSectionEditor({
   const readOnly = page.builderOwned
   const effectiveCanEdit = canEdit && !readOnly
 
+  // Sections whose type has no registered definition (seed/code-owned, e.g.
+  // `opal-*`). They are preserved verbatim on save but can't be edited here.
+  const unmanagedTypes = Array.from(
+    new Set(page.sections.filter((s) => s.unmanaged).map((s) => s.sectionType)),
+  )
+
   return (
     <ErrorBoundary>
       <div className="bg-background flex h-full flex-col overflow-hidden">
@@ -436,6 +442,23 @@ export function PageSectionEditor({
           </div>
         )}
 
+        {unmanagedTypes.length > 0 && (
+          <div
+            role="status"
+            className="border-border bg-muted/50 flex items-start gap-3 border-b px-4 py-2.5"
+          >
+            <Lock className="text-muted-foreground mt-0.5 shrink-0" size={16} aria-hidden />
+            <p className="text-muted-foreground flex-1 text-sm">
+              This page has{' '}
+              <span className="text-foreground font-medium">
+                {unmanagedTypes.length} section type{unmanagedTypes.length > 1 ? 's' : ''}
+              </span>{' '}
+              managed outside the editor ({unmanagedTypes.join(', ')}). They are preserved on save
+              but edited in your seed script or code, not here.
+            </p>
+          </div>
+        )}
+
         {validation && (
           <ValidationSummary
             errors={validation.errors}