kilo-cms 0.1.0

package/src/admin/ArrayField.tsx

@@ -0,0 +1,118 @@
+'use client'
+
+import { Reorder, useDragControls } from 'framer-motion'
+import { Button } from './Button'
+import { DynamicField } from './DynamicField'
+import { Field } from './Field'
+import { DragHandle } from './DragHandle'
+import { useKeyedRows, type KeyedRow, type Row } from './useKeyedRows'
+import type { AnyFieldConfig, ArrayItemFieldConfig } from '../collections/types'
+import { blankValueForField, formatFieldValue, isFieldVisible } from '../collections/values'
+
+// A top-level `array` field or a block's own nested `array` sub-field (see BlockFieldConfig) —
+// both render through this same component; they differ only in the top-level-only FieldBase
+// props (group/readOnly/…), which ArrayField never reads.
+type ArrayFieldConfig = Extract<AnyFieldConfig, { type: 'array' }>
+
+function blankRow(fields: ArrayItemFieldConfig[]): Row {
+  return Object.fromEntries(fields.map((subfield) => [subfield.key, blankValueForField(subfield)]))
+}
+
+function ArrayRow({ index, fields, item, onChange, onRemove }: {
+  index: number
+  fields: ArrayItemFieldConfig[]
+  item: KeyedRow
+  onChange: (row: Row) => void
+  onRemove: () => void
+}) {
+  const controls = useDragControls()
+  const row = item.row
+  return (
+    // `value` MUST be the exact object reference that appears in the enclosing Reorder.Group's
+    // `values` array (here, `items`) — framer-motion tracks drag position by `values.indexOf(value)`.
+    // Passing `row` (the inner value) instead of `item` (the KeyedRow wrapper) silently breaks
+    // reordering entirely, since it never matches anything in `values`.
+    <Reorder.Item value={item} dragListener={false} dragControls={controls} className="cms-array-row">
+      <div className="cms-array-row-head">
+        <button type="button" className="cms-array-row-grip" onPointerDown={(event) => controls.start(event)} aria-label={`Drag to reorder item ${index + 1}`}><DragHandle /></button>
+        <span className="cms-array-row-index">{index + 1}</span>
+        <Button type="button" variant="ghost" compact onClick={onRemove} aria-label={`Remove item ${index + 1}`}>Remove</Button>
+      </div>
+      <div className="cms-content-field-grid">
+        {fields.filter((subfield) => isFieldVisible(subfield, row)).map((subfield) => (
+          <div key={subfield.key} className={`cms-content-field cms-content-field-${subfield.width ?? 'full'}`}>
+            <DynamicField
+              field={subfield}
+              value={row[subfield.key]}
+              onChange={(value) => onChange({ ...row, [subfield.key]: value })}
+              label={subfield.label}
+              hint={subfield.hint}
+            />
+          </div>
+        ))}
+      </div>
+    </Reorder.Item>
+  )
+}
+
+export function ArrayField({ field, value, onChange, label, hint, error, disabled }: {
+  field: ArrayFieldConfig
+  value: Row[]
+  onChange: (rows: Row[]) => void
+  label: string
+  hint?: string
+  error?: string
+  disabled?: boolean
+}) {
+  const { items, emit } = useKeyedRows(value, onChange)
+  const itemNoun = field.itemLabel ?? 'item'
+
+  if (disabled) {
+    return (
+      <Field label={label} required={field.required} hint={hint} error={error}>
+        <div className="cms-array-field cms-array-readonly">
+          {value.length
+            ? value.map((row, index) => (
+                <div className="cms-array-row cms-array-row-readonly" key={index}>
+                  {field.fields.filter((subfield) => isFieldVisible(subfield, row)).map((subfield) => (
+                    <div className="cms-array-readonly-cell" key={subfield.key}>
+                      <span className="cms-array-readonly-label">{subfield.label}</span>
+                      <span>{formatFieldValue(subfield, row[subfield.key])}</span>
+                    </div>
+                  ))}
+                </div>
+              ))
+            : <span className="cms-muted-value">—</span>}
+        </div>
+      </Field>
+    )
+  }
+
+  const atMax = typeof field.maxItems === 'number' && items.length >= field.maxItems
+
+  return (
+    <Field label={label} required={field.required} hint={hint} error={error}>
+      <div className="cms-array-field">
+        {items.length
+          ? (
+              <Reorder.Group axis="y" values={items} onReorder={emit} className="cms-array-rows">
+                {items.map((item, index) => (
+                  <ArrayRow
+                    key={item.id}
+                    index={index}
+                    fields={field.fields}
+                    item={item}
+                    onChange={(row) => emit(items.map((entry) => (entry.id === item.id ? { ...entry, row } : entry)))}
+                    onRemove={() => emit(items.filter((entry) => entry.id !== item.id))}
+                  />
+                ))}
+              </Reorder.Group>
+            )
+          : <p className="cms-array-empty">No {itemNoun}s yet.</p>}
+        <Button type="button" variant="secondary" compact className="cms-array-add" onClick={() => emit([...items, { id: crypto.randomUUID(), row: blankRow(field.fields) }])} disabled={atMax}>
+          + Add {itemNoun}
+        </Button>
+      </div>
+    </Field>
+  )
+}

package/src/admin/BlocksField.tsx

@@ -0,0 +1,131 @@
+'use client'
+
+import { Reorder, useDragControls } from 'framer-motion'
+import { Button } from './Button'
+import { DragHandle } from './DragHandle'
+import { DynamicField } from './DynamicField'
+import { Field } from './Field'
+import { useKeyedRows, type KeyedRow, type Row } from './useKeyedRows'
+import type { BlockTypeDef, FieldConfig } from '../collections/types'
+import { blankValueForField, formatFieldValue, isFieldVisible } from '../collections/values'
+
+type BlocksFieldConfig = Extract<FieldConfig, { type: 'blocks' }>
+
+function blankBlock(blockDef: BlockTypeDef): Row {
+  return { blockType: blockDef.type, ...Object.fromEntries(blockDef.fields.map((subfield) => [subfield.key, blankValueForField(subfield)])) }
+}
+
+function BlockRow({ index, blockDef, item, onChange, onRemove }: {
+  index: number
+  blockDef: BlockTypeDef | undefined
+  item: KeyedRow
+  onChange: (row: Row) => void
+  onRemove: () => void
+}) {
+  const controls = useDragControls()
+  const row = item.row
+  return (
+    // `value` MUST be the exact object reference in the enclosing Reorder.Group's `values`
+    // array (here, `items`) — framer-motion tracks drag position by `values.indexOf(value)`.
+    <Reorder.Item value={item} dragListener={false} dragControls={controls} className="cms-array-row">
+      <div className="cms-array-row-head">
+        <button type="button" className="cms-array-row-grip" onPointerDown={(event) => controls.start(event)} aria-label={`Drag to reorder block ${index + 1}`}><DragHandle /></button>
+        <span className="cms-block-type-badge">{blockDef?.label ?? String(row.blockType ?? '?')}</span>
+        <span className="cms-array-row-index">{index + 1}</span>
+        <Button type="button" variant="ghost" compact onClick={onRemove} aria-label={`Remove block ${index + 1}`}>Remove</Button>
+      </div>
+      {blockDef && (
+        <div className="cms-content-field-grid">
+          {blockDef.fields.filter((subfield) => isFieldVisible(subfield, row)).map((subfield) => (
+            <div key={subfield.key} className={`cms-content-field cms-content-field-${subfield.width ?? 'full'}`}>
+              <DynamicField
+                field={subfield}
+                value={row[subfield.key]}
+                onChange={(value) => onChange({ ...row, [subfield.key]: value })}
+                label={subfield.label}
+                hint={subfield.hint}
+              />
+            </div>
+          ))}
+        </div>
+      )}
+    </Reorder.Item>
+  )
+}
+
+export function BlocksField({ field, value, onChange, label, hint, error, disabled }: {
+  field: BlocksFieldConfig
+  value: Row[]
+  onChange: (rows: Row[]) => void
+  label: string
+  hint?: string
+  error?: string
+  disabled?: boolean
+}) {
+  const { items, emit } = useKeyedRows(value, onChange)
+  const blockDefFor = (blockType: unknown) => field.blockTypes.find((def) => def.type === blockType)
+
+  if (disabled) {
+    return (
+      <Field label={label} required={field.required} hint={hint} error={error}>
+        <div className="cms-array-field cms-array-readonly">
+          {value.length
+            ? value.map((row, index) => {
+                const blockDef = blockDefFor(row.blockType)
+                return (
+                  <div className="cms-array-row cms-array-row-readonly" key={index}>
+                    <span className="cms-block-type-badge">{blockDef?.label ?? String(row.blockType ?? '?')}</span>
+                    {blockDef?.fields.filter((subfield) => isFieldVisible(subfield, row)).map((subfield) => (
+                      <div className="cms-array-readonly-cell" key={subfield.key}>
+                        <span className="cms-array-readonly-label">{subfield.label}</span>
+                        <span>{formatFieldValue(subfield, row[subfield.key])}</span>
+                      </div>
+                    ))}
+                  </div>
+                )
+              })
+            : <span className="cms-muted-value">—</span>}
+        </div>
+      </Field>
+    )
+  }
+
+  const atMax = typeof field.maxItems === 'number' && items.length >= field.maxItems
+
+  return (
+    <Field label={label} required={field.required} hint={hint} error={error}>
+      <div className="cms-array-field">
+        {items.length
+          ? (
+              <Reorder.Group axis="y" values={items} onReorder={emit} className="cms-array-rows">
+                {items.map((item, index) => (
+                  <BlockRow
+                    key={item.id}
+                    index={index}
+                    blockDef={blockDefFor(item.row.blockType)}
+                    item={item}
+                    onChange={(row) => emit(items.map((entry) => (entry.id === item.id ? { ...entry, row } : entry)))}
+                    onRemove={() => emit(items.filter((entry) => entry.id !== item.id))}
+                  />
+                ))}
+              </Reorder.Group>
+            )
+          : <p className="cms-array-empty">No blocks yet.</p>}
+        <span className="cms-input-shell cms-select-shell cms-blocks-add">
+          <select
+            aria-label="Add a block"
+            value=""
+            disabled={atMax}
+            onChange={(event) => {
+              const blockDef = field.blockTypes.find((def) => def.type === event.target.value)
+              if (blockDef) emit([...items, { id: crypto.randomUUID(), row: blankBlock(blockDef) }])
+            }}
+          >
+            <option value="" disabled>+ Add a block…</option>
+            {field.blockTypes.map((blockDef) => <option key={blockDef.type} value={blockDef.type}>{blockDef.label}</option>)}
+          </select>
+        </span>
+      </div>
+    </Field>
+  )
+}

package/src/admin/Button.tsx

@@ -0,0 +1,31 @@
+import { forwardRef, type AnchorHTMLAttributes, type ButtonHTMLAttributes, type ReactNode, type Ref } from 'react'
+import Link from 'next/link'
+
+export type ButtonVariant = 'primary' | 'positive' | 'negative' | 'secondary' | 'ghost'
+
+type Shared = {
+  variant?: ButtonVariant
+  icon?: ReactNode
+  iconPosition?: 'before' | 'after'
+  iconOnly?: boolean
+  compact?: boolean
+  className?: string
+  children?: ReactNode
+}
+
+type AsButton = Shared & Omit<ButtonHTMLAttributes<HTMLButtonElement>, 'className' | 'children'> & { href?: undefined }
+type AsAnchor = Shared & Omit<AnchorHTMLAttributes<HTMLAnchorElement>, 'className' | 'children'> & { href: string }
+
+export const Button = forwardRef<HTMLButtonElement | HTMLAnchorElement, AsButton | AsAnchor>(function Button(props, ref) {
+  const { variant = 'secondary', icon, iconPosition = 'after', iconOnly, compact, className, children, href, ...rest } = props
+  const classes = ['btn', `btn-${variant}`, iconOnly && 'btn-icon-only', compact && 'btn-compact', className].filter(Boolean).join(' ')
+  const content = iconOnly ? icon : iconPosition === 'before' ? <>{icon}{children}</> : <>{children}{icon}</>
+
+  if (href !== undefined) {
+    const anchorRest = rest as Omit<AnchorHTMLAttributes<HTMLAnchorElement>, 'className' | 'children'>
+    const anchorRef = ref as Ref<HTMLAnchorElement>
+    return href.startsWith('/') ? <Link ref={anchorRef} className={classes} href={href} {...anchorRest}>{content}</Link> : <a ref={anchorRef} className={classes} href={href} {...anchorRest}>{content}</a>
+  }
+  const { type = 'button', ...buttonRest } = rest as Omit<ButtonHTMLAttributes<HTMLButtonElement>, 'className' | 'children'>
+  return <button ref={ref as Ref<HTMLButtonElement>} type={type} className={classes} {...buttonRest}>{content}</button>
+})

package/src/admin/CloseButton.tsx

@@ -0,0 +1,18 @@
+'use client'
+
+import { Button } from './Button'
+
+function CloseIcon() {
+  return <svg width="15" height="15" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2" strokeLinecap="round"><path d="M5 5l14 14M19 5L5 19" /></svg>
+}
+
+type CloseButtonProps = {
+  onClick: () => void
+  variant?: 'icon' | 'text'
+  label?: string
+}
+
+export function CloseButton({ onClick, variant = 'icon', label = 'Close' }: CloseButtonProps) {
+  if (variant === 'text') return <Button variant="ghost" className="cms-close-button cms-close-button-text" onClick={onClick} icon={<CloseIcon />} iconPosition="before">{label}</Button>
+  return <Button variant="secondary" iconOnly className="cms-close-button cms-close-button-icon" onClick={onClick} aria-label={label} title={label} icon={<CloseIcon />} />
+}

package/src/admin/CmsLocalesProvider.tsx

@@ -0,0 +1,19 @@
+'use client'
+
+import { createContext, useContext, type ReactNode } from 'react'
+import type { LocaleConfig } from '../collections/locale'
+
+const CmsLocalesContext = createContext<LocaleConfig | null>(null)
+
+/** Populated once per admin page load from the server (see `(admin)/layout.tsx`, which reads
+ *  `getLocaleConfig()`), same mechanism as `CmsSiteSettingsProvider`. `LocalizedField` reads this
+ *  instead of a static import so admin-added/removed locales show up without a redeploy. */
+export function CmsLocalesProvider({ localeConfig, children }: { localeConfig: LocaleConfig; children: ReactNode }) {
+  return <CmsLocalesContext.Provider value={localeConfig}>{children}</CmsLocalesContext.Provider>
+}
+
+export function useCmsLocales(): LocaleConfig {
+  const context = useContext(CmsLocalesContext)
+  if (!context) throw new Error('useCmsLocales must be used inside CmsLocalesProvider')
+  return context
+}

package/src/admin/CmsSidebar.tsx

@@ -0,0 +1,147 @@
+'use client'
+
+import { useEffect, useRef, useState, type ReactNode } from 'react'
+import { useRouter, usePathname } from 'next/navigation'
+import Link from 'next/link'
+import { authClient } from '../auth-client'
+import type { ContentViewSettings } from '../collections/content-view'
+import { useCmsSiteSettings } from './CmsSiteSettingsProvider'
+import { useCmsTheme } from './CmsThemeProvider'
+
+type Section = 'dashboard' | 'scheduled' | 'review-queue' | 'media' | 'settings' | 'users' | 'roles' | 'collections' | 'singles'
+type IconName = 'grid' | 'calendar' | 'image' | 'gear' | 'logout' | 'users' | 'shield' | 'inbox' | 'layers' | 'database' | 'star' | 'folder' | 'trash'
+type ContentContext = { title: string; backHref: string; backLabel: string; settings: ContentViewSettings }
+type FeatureContext = { title: string; backHref: string; backLabel: string; groups: Array<{ label: string; links: Array<{ label: string; href: string }> }> }
+type MediaView = 'gallery' | 'recent' | 'starred' | 'trash'
+type MediaContext = {
+  view: MediaView
+  onSelect: (view: MediaView) => void
+  stats: { count: number; bytes: number; trashCount: number } | null
+  pinnedFolders: Array<{ slug: string; name: string }>
+  activeFolder: string | null
+  onOpenFolder: (slug: string) => void
+}
+
+function formatBytes(bytes: number) { return bytes >= 1024 * 1024 * 1024 ? `${(bytes / (1024 * 1024 * 1024)).toFixed(1)} GB` : bytes >= 1024 * 1024 ? `${(bytes / (1024 * 1024)).toFixed(1)} MB` : `${Math.round(bytes / 1024)} KB` }
+
+const featureContexts: Partial<Record<Section, FeatureContext>> = {
+  settings: {
+    title: 'Settings', backHref: '/admin/dashboard', backLabel: 'Dashboard',
+    groups: [
+      { label: 'General', links: [{ label: 'Site settings', href: '/admin/settings' }, { label: 'SEO', href: '/admin/settings/seo' }, { label: 'Locales', href: '/admin/settings/locales' }] },
+      { label: 'Integrations', links: [{ label: 'AI writing', href: '/admin/settings/ai' }, { label: 'Email', href: '/admin/settings/email' }] },
+      { label: 'Developers', links: [{ label: 'API tokens', href: '/admin/settings/api-tokens' }, { label: 'Webhooks', href: '/admin/settings/webhooks' }] },
+    ],
+  },
+}
+
+function Icon({ name }: { name: IconName }) {
+  const paths: Record<IconName, ReactNode> = {
+    grid: <><rect x="3" y="3" width="7" height="7" rx="1" /><rect x="14" y="3" width="7" height="7" rx="1" /><rect x="3" y="14" width="7" height="7" rx="1" /><rect x="14" y="14" width="7" height="7" rx="1" /></>,
+    calendar: <><rect x="3" y="4.5" width="18" height="16" rx="2" /><path d="M3 9.5h18M8 2.5v4M16 2.5v4" /><path d="M8 13.5h2M8 17h2M14 13.5h2M14 17h2" /></>,
+    image: <><rect x="3" y="3" width="18" height="18" rx="2" /><circle cx="8.5" cy="9" r="1.6" /><path d="M21 16.5 16 11l-9 9" /></>,
+    gear: <><circle cx="12" cy="12" r="3" /><path d="M19.4 15a1.65 1.65 0 0 0 .33 1.82l.06.06a2 2 0 1 1-2.83 2.83l-.06-.06a1.65 1.65 0 0 0-1.82-.33 1.65 1.65 0 0 0-1 1.51V21a2 2 0 0 1-4 0v-.09A1.65 1.65 0 0 0 9 19.4a1.65 1.65 0 0 0-1.82.33l-.06.06a2 2 0 1 1-2.83-2.83l.06-.06a1.65 1.65 0 0 0 .33-1.82 1.65 1.65 0 0 0-1.51-1H3a2 2 0 0 1 0-4h.09A1.65 1.65 0 0 0 4.6 9a1.65 1.65 0 0 0-.33-1.82l-.06-.06a2 2 0 1 1 2.83-2.83l.06.06a1.65 1.65 0 0 0 1.82.33H9a1.65 1.65 0 0 0 1-1.51V3a2 2 0 0 1 4 0v.09a1.65 1.65 0 0 0 1 1.51 1.65 1.65 0 0 0 1.82-.33l.06-.06a2 2 0 1 1 2.83 2.83l-.06.06a1.65 1.65 0 0 0-.33 1.82V9a1.65 1.65 0 0 0 1.51 1H21a2 2 0 0 1 0 4h-.09a1.65 1.65 0 0 0-1.51 1z" /></>,
+    logout: <><path d="M9 20H5a1 1 0 0 1-1-1V5a1 1 0 0 1 1-1h4" /><path d="M15 16l4-4-4-4" /><path d="M19 12H9" /></>,
+    users: <><circle cx="9" cy="8" r="3.2" /><path d="M3 20c0-3.3 2.7-6 6-6s6 2.7 6 6" /><path d="M16 8.5a3 3 0 1 1 3.5 4.4" /><path d="M21 20c0-2.6-1.7-4.8-4-5.6" /></>,
+    shield: <><path d="M12 3l7 3v6c0 4.5-3 7.5-7 9-4-1.5-7-4.5-7-9V6l7-3Z" /><path d="M9 12l2 2 4-4" /></>,
+    inbox: <><path d="M3 12h4.5l1.5 3h6l1.5-3H21" /><path d="M5.5 6h13l2.5 6v7a1 1 0 0 1-1 1H4a1 1 0 0 1-1-1v-7l2.5-6Z" /></>,
+    layers: <><path d="M12 3l9 4.5-9 4.5-9-4.5 9-4.5Z" /><path d="M3 12l9 4.5 9-4.5" /><path d="M3 16.5l9 4.5 9-4.5" /></>,
+    database: <><ellipse cx="12" cy="6" rx="8" ry="3" /><path d="M4 6v12c0 1.7 3.6 3 8 3s8-1.3 8-3V6" /><path d="M4 12c0 1.7 3.6 3 8 3s8-1.3 8-3" /></>,
+    star: <path d="M12 2.5l2.9 6.2 6.6.7-4.9 4.6 1.3 6.6L12 17.9l-5.9 2.7 1.3-6.6-4.9-4.6 6.6-.7L12 2.5Z" />,
+    folder: <path d="M3 6a2 2 0 0 1 2-2h4l2 2h8a2 2 0 0 1 2 2v9a2 2 0 0 1-2 2H5a2 2 0 0 1-2-2V6Z" />,
+    trash: <><path d="M4 7h16" /><path d="M9 7V5a1 1 0 0 1 1-1h4a1 1 0 0 1 1 1v2" /><path d="M6 7l1 13a1 1 0 0 0 1 1h8a1 1 0 0 0 1-1l1-13" /><path d="M10 11v6M14 11v6" /></>,
+  }
+  return <svg className="cms-nav-icon" width="18" height="18" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="1.6" strokeLinecap="round" strokeLinejoin="round">{paths[name]}</svg>
+}
+
+export function CmsSidebar({ active, userName, contentContext, mediaContext }: { active: Section; userName: string; contentContext?: ContentContext; mediaContext?: MediaContext }) {
+  const router = useRouter()
+  const pathname = usePathname()
+  const session = authClient.useSession()
+  const email = session.data?.user?.email
+  const { settings } = useCmsSiteSettings()
+  const { theme } = useCmsTheme()
+  const [profileOpen, setProfileOpen] = useState(false)
+  const profileMenu = useRef<HTMLDivElement>(null)
+  const [dataLinks, setDataLinks] = useState<Array<{ slug: string; label: string }>>([])
+  const [singleLinks, setSingleLinks] = useState<Array<{ slug: string; label: string }>>([])
+
+  useEffect(() => {
+    fetch('/api/admin/collections').then((response) => response.ok ? response.json() : []).then(setDataLinks).catch(() => {})
+    fetch('/api/admin/singles').then((response) => response.ok ? response.json() : []).then(setSingleLinks).catch(() => {})
+  }, [])
+
+  useEffect(() => {
+    function closeMenu(event: PointerEvent) { if (!profileMenu.current?.contains(event.target as Node)) setProfileOpen(false) }
+    function closeOnEscape(event: KeyboardEvent) { if (event.key === 'Escape') setProfileOpen(false) }
+    document.addEventListener('pointerdown', closeMenu)
+    document.addEventListener('keydown', closeOnEscape)
+    return () => { document.removeEventListener('pointerdown', closeMenu); document.removeEventListener('keydown', closeOnEscape) }
+  }, [])
+
+  async function logout() {
+    setProfileOpen(false)
+    await authClient.signOut()
+    router.push('/admin/login')
+  }
+
+  const initial = userName.trim().charAt(0).toUpperCase() || '?'
+  const logo = theme === 'dark' ? (settings.logoDark ?? settings.logoLight) : (settings.logoLight ?? settings.logoDark)
+  const featureContext = !contentContext ? featureContexts[active] : undefined
+  const isDataSection = active === 'collections' || active === 'singles'
+  const hasSecondaryNav = Boolean(contentContext) || isDataSection || Boolean(mediaContext) || Boolean(featureContext)
+
+  return <aside className={`cms-sidebar${hasSecondaryNav ? '' : ' is-rail-only'}`}>
+    <nav className="cms-feature-rail" aria-label="CMS features">
+      <Link className={`cms-feature-link ${active === 'dashboard' ? 'active' : ''}`} href="/admin/dashboard" data-tooltip="Dashboard"><Icon name="grid" /><span className="sr-only">Dashboard</span></Link>
+      <Link className={`cms-feature-link ${isDataSection ? 'active' : ''}`} href={dataLinks[0]?.slug ? `/admin/collections/${dataLinks[0].slug}` : singleLinks[0]?.slug ? `/admin/single/${singleLinks[0].slug}` : '/admin/dashboard'} data-tooltip="Content"><Icon name="layers" /><span className="sr-only">Content</span></Link>
+      <Link className={`cms-feature-link ${active === 'scheduled' ? 'active' : ''}`} href="/admin/scheduled" data-tooltip="Scheduled"><Icon name="calendar" /><span className="sr-only">Scheduled</span></Link>
+      <Link className={`cms-feature-link ${active === 'review-queue' ? 'active' : ''}`} href="/admin/review-queue" data-tooltip="Review & Approval"><Icon name="inbox" /><span className="sr-only">Review &amp; Approval</span></Link>
+      <Link className={`cms-feature-link ${active === 'media' ? 'active' : ''}`} href="/admin/media" data-tooltip="Media library"><Icon name="image" /><span className="sr-only">Media library</span></Link>
+      <Link className={`cms-feature-link ${active === 'users' ? 'active' : ''}`} href="/admin/users" data-tooltip="Users"><Icon name="users" /><span className="sr-only">Users</span></Link>
+      <Link className={`cms-feature-link ${active === 'roles' ? 'active' : ''}`} href="/admin/roles" data-tooltip="Roles"><Icon name="shield" /><span className="sr-only">Roles</span></Link>
+      <Link className={`cms-feature-link ${active === 'settings' ? 'active' : ''}`} href="/admin/settings" data-tooltip="Settings"><Icon name="gear" /><span className="sr-only">Settings</span></Link>
+      <div className="cms-account-mark" ref={profileMenu}>
+        <button type="button" className="cms-profile-trigger" onClick={() => setProfileOpen((open) => !open)} aria-haspopup="menu" aria-expanded={profileOpen} aria-label={`Account: ${userName}`}><span className="cms-avatar">{initial}</span></button>
+        {profileOpen && <div className="cms-profile-menu" role="menu">
+          <div className="cms-profile-menu-user"><span className="cms-avatar">{initial}</span><span className="cms-profile-menu-text"><strong>{userName}</strong>{email && <small>{email}</small>}</span></div>
+          <button type="button" role="menuitem" onClick={() => void logout()}><span>Sign out</span><Icon name="logout" /></button>
+        </div>}
+      </div>
+    </nav>
+    <Link className="cms-brand-mark" href="/admin/dashboard" aria-label={`${settings.siteName} — Dashboard`}>{logo ? <img src={logo} alt="" className="cms-brand-logo" /> : <span className="cms-brand-logo-placeholder" aria-hidden="true" />}</Link>
+    <Link className="cms-brand-word" href="/admin/dashboard">{settings.siteName}</Link>
+    {contentContext ? <nav className="cms-nav cms-context-nav" aria-label={`${contentContext.title} editor navigation`}>
+      <div className="cms-context-title"><p className="cms-nav-label">Content editor</p><strong>{contentContext.title}</strong></div>
+      <div className="cms-context-groups">{contentContext.settings.groups.map((group) => {
+        const fields = contentContext.settings.fields.filter((field) => field.groupId === group.id)
+        if (!fields.length) return null
+        return <section className="cms-context-group" key={group.id}><a href={`#cms-group-${group.id}`}>{group.label}</a><div>{fields.map((field) => <a href={`#cms-field-${field.key}`} key={field.key}>{field.label}</a>)}</div></section>
+      })}</div>
+    </nav> : isDataSection ? <nav className="cms-nav" aria-label="Content navigation">
+      {singleLinks.length > 0 && <>
+        <p className="cms-nav-label">Single types</p>
+        {singleLinks.map((link) => <Link key={link.slug} className={`cms-nav-link ${pathname.startsWith(`/admin/single/${link.slug}`) ? 'active' : ''}`} href={`/admin/single/${link.slug}`}><Icon name="layers" />{link.label}</Link>)}
+      </>}
+      <p className="cms-nav-label">Collections</p>
+      {dataLinks.map((link) => <Link key={link.slug} className={`cms-nav-link ${pathname.startsWith(`/admin/collections/${link.slug}`) ? 'active' : ''}`} href={`/admin/collections/${link.slug}`}><Icon name="database" />{link.label}</Link>)}
+    </nav> : mediaContext ? <nav className="cms-nav" aria-label="Media library navigation">
+      <p className="cms-nav-label">Media library</p>
+      <button type="button" className={`cms-nav-link ${mediaContext.view === 'gallery' ? 'active' : ''}`} onClick={() => mediaContext.onSelect('gallery')}><Icon name="image" />Files</button>
+      <button type="button" className={`cms-nav-link ${mediaContext.view === 'recent' ? 'active' : ''}`} onClick={() => mediaContext.onSelect('recent')}><Icon name="calendar" />Recent</button>
+      <button type="button" className={`cms-nav-link ${mediaContext.view === 'starred' ? 'active' : ''}`} onClick={() => mediaContext.onSelect('starred')}><Icon name="star" />Starred</button>
+      <button type="button" className={`cms-nav-link ${mediaContext.view === 'trash' ? 'active' : ''}`} onClick={() => mediaContext.onSelect('trash')}><Icon name="trash" />Trash{!!mediaContext.stats?.trashCount && <span className="cms-nav-badge">{mediaContext.stats.trashCount}</span>}</button>
+      {mediaContext.pinnedFolders.length > 0 && <>
+        <p className="cms-nav-label">Pinned folders</p>
+        {mediaContext.pinnedFolders.map((folder) => <button type="button" key={folder.slug} className={`cms-nav-link ${mediaContext.activeFolder === folder.slug ? 'active' : ''}`} onClick={() => mediaContext.onOpenFolder(folder.slug)}><Icon name="folder" />{folder.name}</button>)}
+      </>}
+      {mediaContext.stats && <div className="cms-media-stats">
+        <div><span>Storage used</span><strong>{formatBytes(mediaContext.stats.bytes)}</strong></div>
+        <div><span>Total files</span><strong>{mediaContext.stats.count}</strong></div>
+      </div>}
+    </nav> : featureContext ? <nav className="cms-nav cms-context-nav" aria-label={`${featureContext.title} navigation`}>
+      <div className="cms-context-title"><p className="cms-nav-label">CMS feature</p><strong>{featureContext.title}</strong></div>
+      <div className="cms-context-groups">{featureContext.groups.map((group) => <section className="cms-context-group" key={group.label}><Link href={group.links[0]?.href ?? '/admin/settings'}>{group.label}</Link><div>{group.links.map((link) => <Link href={link.href} className={pathname === link.href ? 'active' : ''} key={link.href}>{link.label}</Link>)}</div></section>)}</div>
+    </nav> : null}
+  </aside>
+}

package/src/admin/CmsSiteSettingsProvider.tsx

@@ -0,0 +1,30 @@
+'use client'
+
+import { createContext, useContext, useMemo, useState, type ReactNode } from 'react'
+import type { PublishingWorkflow } from '../publishing-workflow'
+
+export type CmsSiteSettings = {
+  siteName: string
+  logoLight: string | null
+  logoDark: string | null
+  publishingWorkflow: PublishingWorkflow
+}
+
+type CmsSiteSettingsContextValue = {
+  settings: CmsSiteSettings
+  setSettings: (settings: CmsSiteSettings) => void
+}
+
+const CmsSiteSettingsContext = createContext<CmsSiteSettingsContextValue | null>(null)
+
+export function CmsSiteSettingsProvider({ initialSettings, children }: { initialSettings: CmsSiteSettings; children: ReactNode }) {
+  const [settings, setSettings] = useState(initialSettings)
+  const value = useMemo(() => ({ settings, setSettings }), [settings])
+  return <CmsSiteSettingsContext.Provider value={value}>{children}</CmsSiteSettingsContext.Provider>
+}
+
+export function useCmsSiteSettings() {
+  const context = useContext(CmsSiteSettingsContext)
+  if (!context) throw new Error('useCmsSiteSettings must be used inside CmsSiteSettingsProvider')
+  return context
+}

package/src/admin/CmsThemeProvider.tsx

@@ -0,0 +1,100 @@
+'use client'
+
+import { createContext, useContext, useEffect, useState, useSyncExternalStore, type ReactNode } from 'react'
+import { appearanceCssVariables, defaultCmsAppearance, normalizeCmsAppearance, type CmsAppearance } from '../cms-appearance'
+
+export type CmsTheme = 'light' | 'dark'
+export type CmsThemePreference = CmsTheme | 'system'
+const STORAGE_KEY = 'cms-theme'
+const listeners = new Set<() => void>()
+
+function subscribe(listener: () => void) {
+  listeners.add(listener)
+  return () => listeners.delete(listener)
+}
+
+function getSnapshot(): CmsTheme {
+  return typeof document !== 'undefined' && document.documentElement.dataset.theme === 'dark' ? 'dark' : 'light'
+}
+
+function getServerSnapshot(): CmsTheme { return 'light' }
+
+function systemPrefersDark() {
+  return typeof window !== 'undefined' && window.matchMedia('(prefers-color-scheme: dark)').matches
+}
+
+// No explicit choice stored yet ⇒ follow the device's own theme, per OS preference.
+function resolveTheme(preference: CmsThemePreference): CmsTheme {
+  return preference === 'system' ? (systemPrefersDark() ? 'dark' : 'light') : preference
+}
+
+function readStoredPreference(): CmsThemePreference {
+  try {
+    const stored = window.localStorage.getItem(STORAGE_KEY)
+    return stored === 'dark' || stored === 'light' ? stored : 'system'
+  } catch { return 'system' }
+}
+
+function applyTheme(theme: CmsTheme) {
+  document.documentElement.dataset.theme = theme
+  listeners.forEach((listener) => listener())
+}
+
+function applyAppearance(appearance: CmsAppearance, theme: CmsTheme) {
+  if (typeof document === 'undefined') return
+  for (const [name, value] of Object.entries(appearanceCssVariables(appearance, theme))) document.documentElement.style.setProperty(name, value)
+}
+
+type ThemeContextValue = {
+  theme: CmsTheme
+  preference: CmsThemePreference
+  setPreference: (preference: CmsThemePreference) => void
+  appearance: CmsAppearance
+  setAppearance: (appearance: CmsAppearance) => void
+}
+const ThemeContext = createContext<ThemeContextValue | null>(null)
+
+export function CmsThemeProvider({ initialAppearance = defaultCmsAppearance, children }: { initialAppearance?: CmsAppearance; children: ReactNode }) {
+  const theme = useSyncExternalStore(subscribe, getSnapshot, getServerSnapshot)
+  const [appearance, setAppearanceState] = useState(() => normalizeCmsAppearance(initialAppearance))
+  const [preference, setPreferenceState] = useState<CmsThemePreference>('system')
+
+  // Sync the stored preference into state once mounted (the boot script already
+  // applied the correct data-theme before paint — this is only for the settings UI).
+  useEffect(() => { setPreferenceState(readStoredPreference()) }, [])
+
+  // Live-follow the OS theme while the preference is 'system'.
+  useEffect(() => {
+    if (preference !== 'system') return
+    const media = window.matchMedia('(prefers-color-scheme: dark)')
+    function onChange() {
+      const resolved = resolveTheme('system')
+      applyTheme(resolved)
+      applyAppearance(appearance, resolved)
+    }
+    media.addEventListener('change', onChange)
+    return () => media.removeEventListener('change', onChange)
+  }, [preference, appearance])
+
+  function setPreference(next: CmsThemePreference) {
+    setPreferenceState(next)
+    try { window.localStorage.setItem(STORAGE_KEY, next) } catch { /* localStorage can be unavailable */ }
+    const resolved = resolveTheme(next)
+    applyTheme(resolved)
+    applyAppearance(appearance, resolved)
+  }
+
+  function setAppearance(nextAppearance: CmsAppearance) {
+    const normalized = normalizeCmsAppearance(nextAppearance)
+    setAppearanceState(normalized)
+    applyAppearance(normalized, theme)
+  }
+
+  return <ThemeContext.Provider value={{ theme, preference, setPreference, appearance, setAppearance }}>{children}</ThemeContext.Provider>
+}
+
+export function useCmsTheme() {
+  const context = useContext(ThemeContext)
+  if (!context) throw new Error('useCmsTheme must be used inside CmsThemeProvider')
+  return context
+}