@prenta/admin 1.9.2 → 1.10.1

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

@@ -21,6 +21,17 @@ export interface CanvasSurfaceProps {
   onCanvasElement?: (el: HTMLElement | null) => void
   /** Tips, notices, or the review bar — rendered above the meta line. */
   chrome?: React.ReactNode
+  /** Theme-chrome health strip — locale, slot status, outline warning. */
+  health?: React.ReactNode
+  /** `lang` on `.prenta-canvas` when theme chrome is mounted. */
+  lang?: string
+  /** `dir` on `.prenta-canvas` when theme chrome is mounted. */
+  dir?: 'ltr' | 'rtl'
+  /**
+   * `frame` fills the remaining pane and expects children to scroll internally.
+   * `flow` (default) sizes the canvas from content height, as today.
+   */
+  fillMode?: 'flow' | 'frame'
   /** The page itself. Rendered inside the scaled, container-queried surface. */
   children: React.ReactNode
 }
@@ -57,14 +68,22 @@ export function CanvasSurface({
   onScaleChange,
   onCanvasElement,
   chrome,
+  health,
+  lang,
+  dir,
+  fillMode = 'flow',
   children,
 }: CanvasSurfaceProps) {
   const bp = getBreakpoint(breakpoint)
   const sentinelRef = useRef<HTMLDivElement>(null)
   const surfaceRef = useRef<HTMLDivElement>(null)
+  const areaRef = useRef<HTMLDivElement>(null)
 
   const [available, setAvailable] = useState(0)
   const [pageHeight, setPageHeight] = useState(0)
+  const [areaHeight, setAreaHeight] = useState(0)
+
+  const isFrame = fillMode === 'frame'
 
   // No dependency array: page height changes on edits that resize nothing the
   // observer watches. Both setters bail when the value is unchanged, so this
@@ -76,6 +95,9 @@ export function CanvasSurface({
 
       const height = surfaceRef.current?.offsetHeight ?? 0
       if (height > 0) setPageHeight((prev) => (prev === height ? prev : height))
+
+      const area = areaRef.current?.clientHeight ?? 0
+      if (area > 0) setAreaHeight((prev) => (prev === area ? prev : area))
     }
 
     measure()
@@ -83,10 +105,12 @@ export function CanvasSurface({
     const ro = new ResizeObserver(measure)
     if (sentinelRef.current) ro.observe(sentinelRef.current)
     if (surfaceRef.current) ro.observe(surfaceRef.current)
+    if (areaRef.current) ro.observe(areaRef.current)
     return () => ro.disconnect()
   })
 
   const scale = fitScale(available, bp.width, zoom)
+  const frameUnscaledHeight = isFrame && scale > 0 && areaHeight > 0 ? areaHeight / scale : 0
 
   useEffect(() => {
     onScaleChange?.(scale)
@@ -104,6 +128,7 @@ export function CanvasSurface({
 
       {chrome}
       <CanvasMetaLine breakpoint={bp} pageHeight={pageHeight} scale={scale} />
+      {health}
 
       {/*
        * Fit box: reserves the scaled footprint so the surrounding scroll area
@@ -112,32 +137,41 @@ export function CanvasSurface({
        * that is not visible never finishes one) reports a bogus height and
        * corrupts the next measurement.
        */}
-      <div
-        className="prenta-canvas-fit mx-auto block"
-        style={{
-          width: Math.round(bp.width * scale),
-          height: pageHeight ? Math.round(pageHeight * scale) : undefined,
-        }}
-      >
-        {/* `prenta-canvas` is the public hook for consumer brand CSS: site
-            styles that should render in this preview scope to
-            `.prenta-admin .prenta-canvas` instead of the admin root. It also
-            carries `container-type: inline-size` (theme.css) — that is what
-            makes the `@pv-*` steps in the section renderers resolve against
-            the simulated width instead of the viewport. */}
+      <div ref={areaRef} className={isFrame ? 'relative min-h-0 flex-1' : undefined}>
         <div
-          ref={(el) => {
-            surfaceRef.current = el
-            onCanvasElement?.(el)
-          }}
-          className="prenta-canvas border-border bg-card origin-top-left overflow-hidden rounded-lg text-left shadow-[0_2px_20px_rgba(0,0,0,0.12)] motion-safe:transition-[width,transform] motion-safe:duration-(--mo-slow) motion-safe:ease-(--ease)"
+          className="prenta-canvas-fit mx-auto block"
           style={{
-            width: bp.width,
-            transform: `scale(${scale})`,
-            transformOrigin: 'top left',
+            width: Math.round(bp.width * scale),
+            height: isFrame
+              ? areaHeight || undefined
+              : pageHeight
+                ? Math.round(pageHeight * scale)
+                : undefined,
           }}
         >
-          {children}
+          {/* `prenta-canvas` is the public hook for consumer brand CSS: site
+              styles that should render in this preview scope to
+              `.prenta-admin .prenta-canvas` instead of the admin root. It also
+              carries `container-type: inline-size` (theme.css) — that is what
+              makes the `@pv-*` steps in the section renderers resolve against
+              the simulated width instead of the viewport. */}
+          <div
+            ref={(el) => {
+              surfaceRef.current = el
+              onCanvasElement?.(el)
+            }}
+            lang={lang}
+            dir={dir}
+            className="prenta-canvas border-border bg-card origin-top-left overflow-hidden rounded-lg text-left shadow-[0_2px_20px_rgba(0,0,0,0.12)] motion-safe:transition-[width,transform] motion-safe:duration-(--mo-slow) motion-safe:ease-(--ease)"
+            style={{
+              width: bp.width,
+              height: isFrame && frameUnscaledHeight ? frameUnscaledHeight : undefined,
+              transform: `scale(${scale})`,
+              transformOrigin: 'top left',
+            }}
+          >
+            {children}
+          </div>
         </div>
       </div>
     </>
@@ -145,9 +179,21 @@ export function CanvasSurface({
 }
 
 /** The scroll container both editors wrap their surface in. */
-export function CanvasScroll({ children }: { children: React.ReactNode }) {
+export function CanvasScroll({
+  children,
+  layout = 'flow',
+}: {
+  children: React.ReactNode
+  layout?: 'flow' | 'frame'
+}) {
   return (
-    <div className="prenta-canvas-scroll bg-muted h-full overflow-auto px-6 pt-4.5 pb-10 text-center">
+    <div
+      className={
+        layout === 'frame'
+          ? 'prenta-canvas-scroll bg-muted flex h-full min-h-0 flex-col overflow-hidden px-6 pt-4.5 pb-10 text-center'
+          : 'prenta-canvas-scroll bg-muted h-full overflow-auto px-6 pt-4.5 pb-10 text-center'
+      }
+    >
       {children}
     </div>
   )

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

@@ -1,12 +1,22 @@
 'use client'
 
+import { useCallback, useMemo, useState } from 'react'
 import { LayoutTemplate } from 'lucide-react'
 import { CanvasEditTip } from '../../components/CanvasEditTip.js'
 import { CanvasScroll, CanvasSurface, useSectionRefs } from './CanvasSurface.js'
 import type { BreakpointId, Zoom } from '../../lib/breakpoints.js'
 import type { PageSection } from '../../lib/page-editor-service.js'
+import {
+  themeChromeEditPath,
+  type AdminThemeChrome,
+  type ThemeChromeDocument,
+  type ThemeChromeEditTarget,
+  type ThemeChromeMode,
+} from '../../lib/theme-chrome.js'
 import { SectionRenderer } from './sections/index.js'
 import { StructureNotice } from './StructureNotice.js'
+import { ThemeChromeFrame, ThemeChromeHealth } from './theme-chrome/index.js'
+import type { ThemeChromeHealthState } from './theme-chrome/ThemeChromeFrame.js'
 
 interface EditorCanvasProps {
   sections: PageSection[]
@@ -31,6 +41,16 @@ interface EditorCanvasProps {
    * to the editor's history state, which the canvas knows nothing about.
    */
   reviewBar?: React.ReactNode
+  /** When set and enabled, wraps bands in site header/footer. */
+  themeChrome?: {
+    spec: AdminThemeChrome
+    enabled: boolean
+    mode: ThemeChromeMode
+    locale: string
+    dir: 'ltr' | 'rtl'
+    document: ThemeChromeDocument
+    onNavigate: (path: string) => void
+  }
 }
 
 /**
@@ -52,13 +72,44 @@ export function EditorCanvas({
   reviewing = false,
   changedSectionIds,
   reviewBar,
+  themeChrome,
 }: EditorCanvasProps) {
   const registerRef = useSectionRefs(selectedId)
+  const [health, setHealth] = useState<ThemeChromeHealthState | null>(null)
+
+  const chromeOn = Boolean(themeChrome?.enabled)
+  const mode = themeChrome?.mode ?? 'flow'
+
+  const onEditChrome = useCallback(
+    (target: ThemeChromeEditTarget) => {
+      themeChrome?.onNavigate(themeChromeEditPath(target))
+    },
+    [themeChrome],
+  )
+
+  const documentIdentity = themeChrome?.document
+
+  const bands = useMemo(() => {
+    if (sections.length === 0) return <EmptyCanvas />
+    return sections.map((section) => (
+      <SectionRenderer
+        key={section.id}
+        section={section}
+        editable
+        reviewing={reviewing}
+        changed={changedSectionIds?.has(section.id) ?? false}
+        selected={section.id === selectedId}
+        onSelect={onSelect}
+        registerRef={registerRef}
+      />
+    ))
+  }, [sections, reviewing, changedSectionIds, selectedId, onSelect, registerRef])
 
   // A design-owned page always ships the template's sections, so an empty
   // canvas means the template resolved to nothing — a configuration problem,
-  // not a page to scale and measure.
-  if (sections.length === 0) {
+  // not a page to scale and measure. Theme chrome still mounts so editors
+  // can see and edit the site shell.
+  if (sections.length === 0 && !chromeOn) {
     return (
       <CanvasScroll>
         <EmptyCanvas />
@@ -66,13 +117,47 @@ export function EditorCanvas({
     )
   }
 
+  const inner =
+    chromeOn && themeChrome && documentIdentity ? (
+      <ThemeChromeFrame
+        spec={themeChrome.spec}
+        mode={mode}
+        breakpoint={breakpoint}
+        locale={themeChrome.locale}
+        dir={themeChrome.dir}
+        document={documentIdentity}
+        onEditChrome={onEditChrome}
+        onHealthChange={setHealth}
+      >
+        {bands}
+      </ThemeChromeFrame>
+    ) : (
+      bands
+    )
+
   return (
-    <CanvasScroll>
+    <CanvasScroll layout={chromeOn && mode === 'frame' ? 'frame' : 'flow'}>
       <CanvasSurface
         breakpoint={breakpoint}
         zoom={zoom}
         onScaleChange={onScaleChange}
         onCanvasElement={onCanvasElement}
+        lang={chromeOn ? themeChrome?.locale : undefined}
+        dir={chromeOn ? themeChrome?.dir : undefined}
+        fillMode={chromeOn && mode === 'frame' ? 'frame' : 'flow'}
+        health={
+          chromeOn && themeChrome && health ? (
+            <ThemeChromeHealth
+              locale={themeChrome.locale}
+              dir={themeChrome.dir}
+              header={health.header}
+              footer={health.footer}
+              outlineWarning={health.outlineWarning}
+              navLinkCount={themeChrome.spec.diagnostics?.navLinkCount}
+              brandPresent={themeChrome.spec.diagnostics?.brandPresent}
+            />
+          ) : undefined
+        }
         chrome={
           // The review bar REPLACES the editing chrome rather than joining it:
           // a tip about clicking sections to edit them is actively wrong while
@@ -87,18 +172,7 @@ export function EditorCanvas({
           )
         }
       >
-        {sections.map((section) => (
-          <SectionRenderer
-            key={section.id}
-            section={section}
-            editable
-            reviewing={reviewing}
-            changed={changedSectionIds?.has(section.id) ?? false}
-            selected={section.id === selectedId}
-            onSelect={onSelect}
-            registerRef={registerRef}
-          />
-        ))}
+        {inner}
       </CanvasSurface>
     </CanvasScroll>
   )

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

@@ -30,6 +30,8 @@ import {
   type WorkflowStage,
 } from '../../lib/workflow-chrome.js'
 import { type ViewportId } from './viewports.js'
+import type { ThemeChromeMode } from '../../lib/theme-chrome.js'
+import { ThemeChromeModeToggle } from './theme-chrome/ThemeChromeModeToggle.js'
 
 export type SaveState = 'idle' | 'saving' | 'saved' | 'error'
 
@@ -56,6 +58,9 @@ interface EditorTopBarProps {
   /** Breadcrumb root label + back-button text (e.g. "Pages" or "Posts"). */
   backLabel?: string
   onViewport: (v: ViewportId) => void
+  /** Theme-chrome Page / Frame toggle. Hidden when theme chrome is off. */
+  chromeMode?: ThemeChromeMode
+  onChromeMode?: (mode: ThemeChromeMode) => void
   onBack: () => void
   /**
    * Open the public site in a new tab. Called with `preview-draft` or
@@ -129,6 +134,8 @@ export function EditorTopBar({
   onZoom,
   backLabel = 'Pages',
   onViewport,
+  chromeMode,
+  onChromeMode,
   onBack,
   onViewOnSite,
   onShare,
@@ -281,6 +288,9 @@ export function EditorTopBar({
           {zoom !== undefined && onZoom && (
             <ZoomChip zoom={zoom} scale={canvasScale ?? 1} onChange={onZoom} />
           )}
+          {chromeMode && onChromeMode ? (
+            <ThemeChromeModeToggle mode={chromeMode} onChange={onChromeMode} />
+          ) : null}
         </div>
 
         <button

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

@@ -55,6 +55,15 @@ import { hasCanvasRenderer, useAdminSectionRenderers } from './sections/index.js
 import { EditorTopBar, type SaveState } from './EditorTopBar.js'
 import { SectionsList } from './SectionsPanel.js'
 import { EditorCanvas } from './EditorCanvas.js'
+import { useLocale } from '../../components/LocaleProvider.js'
+import {
+  isThemeChromeEnabled,
+  resolveThemeChromeDir,
+  resolveThemeChromeLocale,
+  resolveThemeChromePath,
+} from '../../lib/theme-chrome.js'
+import { useThemeChromeSpec } from './theme-chrome/ThemeChromeProvider.js'
+import { useThemeChromeMode } from './theme-chrome/useThemeChromeMode.js'
 import { ReflowContext } from './reflow-context.js'
 import { SectionEditForm } from './SectionEditForm.js'
 import { PageSettingsModal } from './PageSettingsModal.js'
@@ -135,6 +144,19 @@ export function PageSectionEditor({
   const [pendingFocusPath, setPendingFocusPath] = useState<string | null>(null)
   const [viewport, setViewport] = useState<ViewportId>(DEFAULT_VIEWPORT)
   const [zoom, setZoom] = useState<Zoom>('fit')
+  const themeChromeSpec = useThemeChromeSpec()
+  const themeChromeEnabled = isThemeChromeEnabled(
+    themeChromeSpec,
+    config?.admin?.editor?.themeChrome,
+    'pages',
+  )
+  const [chromeMode, setChromeMode] = useThemeChromeMode(themeChromeSpec?.defaultMode ?? 'flow')
+  const { activeLocale, locales } = useLocale()
+  const chromeLocale = resolveThemeChromeLocale({
+    activeLocale,
+    defaultLocale: config?.i18n?.defaultLocale,
+  })
+  const chromeDir = resolveThemeChromeDir(chromeLocale, locales)
   /**
    * Live audit reported by the SEO pane, built from unsaved form state. Null
    * until that pane has mounted — `audit` below falls back to the saved-record
@@ -881,6 +903,8 @@ export function PageSectionEditor({
           zoom={zoom}
           canvasScale={canvasScale}
           onZoom={setZoom}
+          chromeMode={themeChromeEnabled ? chromeMode : undefined}
+          onChromeMode={themeChromeEnabled ? setChromeMode : undefined}
           onBack={() => guardedNavigate('/pages')}
           onViewOnSite={page.id && page.slug ? handleViewOnSite : undefined}
           onShare={page.id ? handleShare : undefined}
@@ -1050,6 +1074,24 @@ export function PageSectionEditor({
                 structuralTypes={structuralTypes}
                 reviewing={reviewing}
                 changedSectionIds={reviewChangedIds}
+                themeChrome={
+                  themeChromeSpec
+                    ? {
+                        spec: themeChromeSpec,
+                        enabled: themeChromeEnabled,
+                        mode: chromeMode,
+                        locale: chromeLocale,
+                        dir: chromeDir,
+                        document: {
+                          id: page.id,
+                          title: page.title,
+                          path: resolveThemeChromePath(page.path, page.slug),
+                          collection: PAGES_COLLECTION,
+                        },
+                        onNavigate,
+                      }
+                    : undefined
+                }
                 reviewBar={
                   reviewVersion ? (
                     <ReviewBar

package/src/views/page-editor/section-types.ts

@@ -11,6 +11,8 @@ export {
   SECTION_TYPE_LIST,
   getSectionType,
   getSectionTypesForScope,
+  getAddableSectionTypesForScope,
+  isSectionTypeAddable,
   sectionTypeLabel,
   isKnownSectionType,
   resolveRepeaterField,

package/src/views/page-editor/theme-chrome/ThemeChromeFrame.tsx

@@ -0,0 +1,119 @@
+'use client'
+
+import { useCallback, useEffect, useMemo, useState, type ReactNode } from 'react'
+import {
+  THEME_CHROME_MAIN_ID,
+  type AdminThemeChrome,
+  type AdminThemeChromeProps,
+  type ThemeChromeDocument,
+  type ThemeChromeEditTarget,
+  type ThemeChromeMode,
+  type ThemeChromeSlotStatus,
+} from '../../../lib/theme-chrome.js'
+import type { BreakpointId } from '../../../lib/breakpoints.js'
+import { ThemeChromeSlot } from './ThemeChromeSlot.js'
+
+export interface ThemeChromeHealthState {
+  header: ThemeChromeSlotStatus
+  footer: ThemeChromeSlotStatus
+  outlineWarning: boolean
+}
+
+export interface ThemeChromeFrameProps {
+  spec: AdminThemeChrome
+  mode: ThemeChromeMode
+  breakpoint: BreakpointId
+  locale: string
+  dir: 'ltr' | 'rtl'
+  document: ThemeChromeDocument
+  onEditChrome: (target: ThemeChromeEditTarget) => void
+  onHealthChange?: (health: ThemeChromeHealthState) => void
+  children: ReactNode
+}
+
+export function ThemeChromeFrame({
+  spec,
+  mode,
+  breakpoint,
+  locale,
+  dir,
+  document,
+  onEditChrome,
+  onHealthChange,
+  children,
+}: ThemeChromeFrameProps) {
+  const [headerStatus, setHeaderStatus] = useState<ThemeChromeSlotStatus>('placeholder')
+  const [footerStatus, setFooterStatus] = useState<ThemeChromeSlotStatus>('placeholder')
+  const [headerH1, setHeaderH1] = useState(false)
+  const [footerH1, setFooterH1] = useState(false)
+
+  const chromeProps = useMemo<Omit<AdminThemeChromeProps, 'region'>>(
+    () => ({
+      breakpoint,
+      mode,
+      preview: true,
+      locale,
+      dir,
+      document,
+      onEditChrome,
+    }),
+    [breakpoint, mode, locale, dir, document, onEditChrome],
+  )
+
+  const onHeaderOutline = useCallback((hasH1: boolean) => setHeaderH1(hasH1), [])
+  const onFooterOutline = useCallback((hasH1: boolean) => setFooterH1(hasH1), [])
+
+  useEffect(() => {
+    onHealthChange?.({
+      header: headerStatus,
+      footer: footerStatus,
+      outlineWarning: headerH1 || footerH1,
+    })
+  }, [headerStatus, footerStatus, headerH1, footerH1, onHealthChange])
+
+  const headerProps: AdminThemeChromeProps = { ...chromeProps, region: 'header' }
+  const footerProps: AdminThemeChromeProps = { ...chromeProps, region: 'footer' }
+
+  const frameClass = mode === 'frame' ? 'flex h-full min-h-0 flex-col' : 'flex min-h-0 flex-col'
+
+  return (
+    <div
+      className={frameClass}
+      data-prenta-theme-chrome-mode={mode}
+      data-prenta-theme-chrome-locale={locale}
+      data-prenta-theme-chrome-dir={dir}
+      data-prenta-theme-chrome-path={document.path}
+    >
+      <a
+        href={`#${THEME_CHROME_MAIN_ID}`}
+        className="bg-primary text-primary-foreground sr-only focus:not-sr-only focus:absolute focus:top-2 focus:left-2 focus:z-30 focus:rounded-md focus:px-3 focus:py-1.5 focus:text-sm"
+      >
+        Skip to content
+      </a>
+      <div className={mode === 'frame' ? 'shrink-0' : undefined}>
+        <ThemeChromeSlot
+          region="header"
+          spec={spec}
+          chromeProps={headerProps}
+          onOutlineIssue={onHeaderOutline}
+          onStatus={setHeaderStatus}
+        />
+      </div>
+      <div
+        id={THEME_CHROME_MAIN_ID}
+        className={mode === 'frame' ? 'min-h-0 flex-1 overflow-auto' : undefined}
+      >
+        {children}
+      </div>
+      <div className={mode === 'frame' ? 'shrink-0' : undefined}>
+        <ThemeChromeSlot
+          region="footer"
+          spec={spec}
+          chromeProps={footerProps}
+          onOutlineIssue={onFooterOutline}
+          onStatus={setFooterStatus}
+        />
+      </div>
+    </div>
+  )
+}

package/src/views/page-editor/theme-chrome/ThemeChromeHealth.tsx

@@ -0,0 +1,66 @@
+'use client'
+
+import type { ThemeChromeSlotStatus } from '../../../lib/theme-chrome.js'
+
+export interface ThemeChromeHealthProps {
+  locale: string
+  dir: 'ltr' | 'rtl'
+  header: ThemeChromeSlotStatus
+  footer: ThemeChromeSlotStatus
+  outlineWarning: boolean
+  navLinkCount?: number
+  brandPresent?: boolean
+}
+
+const STATUS_LABEL: Record<ThemeChromeSlotStatus, string> = {
+  ok: 'ok',
+  preview: 'preview',
+  fallback: 'fallback',
+  placeholder: 'View site',
+}
+
+export function ThemeChromeHealth({
+  locale,
+  dir,
+  header,
+  footer,
+  outlineWarning,
+  navLinkCount,
+  brandPresent,
+}: ThemeChromeHealthProps) {
+  return (
+    <p
+      className="text-muted-foreground mb-3 flex flex-wrap items-center justify-center gap-x-1.5 gap-y-1 text-[11px] font-medium tracking-[0.3px]"
+      data-prenta-theme-chrome-health=""
+      aria-live="polite"
+    >
+      <span className="text-foreground/70 uppercase">
+        {locale} · {dir.toUpperCase()}
+      </span>
+      <span aria-hidden>|</span>
+      <span>Header {STATUS_LABEL[header]}</span>
+      <span aria-hidden>|</span>
+      <span>Footer {STATUS_LABEL[footer]}</span>
+      {typeof navLinkCount === 'number' ? (
+        <>
+          <span aria-hidden>|</span>
+          <span>Nav: {navLinkCount} links</span>
+        </>
+      ) : null}
+      {brandPresent === true ? (
+        <>
+          <span aria-hidden>|</span>
+          <span>Brand</span>
+        </>
+      ) : null}
+      {outlineWarning ? (
+        <>
+          <span aria-hidden>|</span>
+          <span className="text-destructive" data-prenta-theme-chrome-outline-warning="">
+            Chrome uses H1 — page outline will be wrong
+          </span>
+        </>
+      ) : null}
+    </p>
+  )
+}

package/src/views/page-editor/theme-chrome/ThemeChromeModeToggle.tsx

@@ -0,0 +1,63 @@
+'use client'
+
+import type { ThemeChromeMode } from '../../../lib/theme-chrome.js'
+
+export interface ThemeChromeModeToggleProps {
+  mode: ThemeChromeMode
+  onChange: (mode: ThemeChromeMode) => void
+}
+
+/**
+ * Page = real document scroll (sellable preview). Frame = pinned chrome
+ * for authoring. Frame is a working view, not the live page.
+ */
+export function ThemeChromeModeToggle({ mode, onChange }: ThemeChromeModeToggleProps) {
+  return (
+    <div
+      role="group"
+      aria-label="Canvas layout. Page scrolls like the live site. Frame pins the header and footer."
+      className="border-border bg-card inline-flex h-[34px] overflow-hidden rounded-lg border"
+    >
+      <ModeButton
+        label="Page"
+        pressed={mode === 'flow'}
+        title="Page — header, bands, and footer scroll together like the live site."
+        onClick={() => onChange('flow')}
+      />
+      <ModeButton
+        label="Frame"
+        pressed={mode === 'frame'}
+        title="Frame — header and footer stay pinned while bands scroll. Authoring view, not the live page."
+        onClick={() => onChange('frame')}
+      />
+    </div>
+  )
+}
+
+function ModeButton({
+  label,
+  pressed,
+  title,
+  onClick,
+}: {
+  label: string
+  pressed: boolean
+  title: string
+  onClick: () => void
+}) {
+  return (
+    <button
+      type="button"
+      aria-pressed={pressed}
+      title={title}
+      onClick={onClick}
+      className={`h-full px-2.5 text-[12.5px] font-medium transition-colors ${
+        pressed
+          ? 'bg-primary text-primary-foreground'
+          : 'text-muted-foreground hover:bg-accent hover:text-accent-foreground'
+      }`}
+    >
+      {label}
+    </button>
+  )
+}