@actuate-media/cms-admin 0.72.3 → 0.74.0

package/src/components/seo/SeoEditorPane.tsx

@@ -7,10 +7,19 @@
  * assists, and `updateSeoFields` save path as the drawer; only the
  * presentation pattern changed.
  */
-import { cloneElement, isValidElement, useEffect, useId, useState, type ReactElement } from 'react'
+import {
+  cloneElement,
+  isValidElement,
+  useEffect,
+  useId,
+  useMemo,
+  useState,
+  type ReactElement,
+} from 'react'
 import { Sparkles, Check, Loader2, Wand2 } from 'lucide-react'
 import { toast } from 'sonner'
 import type { BrandAlignmentScoreResult } from '@actuate-media/cms-core/brand-voice'
+import { resolveRenderedMetaTitle } from '@actuate-media/cms-core/client'
 import {
   fetchSeoContentRecord,
   updateSeoFields,
@@ -148,7 +157,7 @@ export function SeoEditorPane({ entityType, entityId, onClose, onSaved }: SeoEdi
         }
         setRecord(rec)
         setForm({
-          metaTitle: rec.metaTitle ?? '',
+          metaTitle: rec.metaTitlePage ?? '',
           metaDescription: rec.metaDescription ?? '',
           canonicalUrl: rec.canonicalUrl ?? '',
           focusKeyword: rec.focusKeyword ?? '',
@@ -182,11 +191,20 @@ export function SeoEditorPane({ entityType, entityId, onClose, onSaved }: SeoEdi
         return
       }
       if (result.text) {
-        update({ [field]: result.text } as Partial<SeoFieldPayload>)
+        const targetField =
+          field === 'ogTitle' ? 'metaTitle' : field === 'ogDescription' ? 'metaDescription' : field
+        const patch: Partial<SeoFieldPayload> = { [targetField]: result.text }
+        if (field === 'ogTitle') patch.ogTitle = ''
+        if (field === 'ogDescription') patch.ogDescription = ''
+        update(patch)
         if (result.brandAlignment) {
-          setAiAlignments((prev) => ({ ...prev, [field]: result.brandAlignment }))
+          setAiAlignments((prev) => ({ ...prev, [targetField]: result.brandAlignment }))
         }
-        toast.success('AI suggestion applied — review before saving.')
+        toast.success(
+          field === 'ogTitle' || field === 'ogDescription'
+            ? 'AI suggestion applied to meta tags — OG inherits from meta unless you override.'
+            : 'AI suggestion applied — review before saving.',
+        )
       } else {
         toast.error('No suggestion was returned.')
       }
@@ -256,7 +274,18 @@ export function SeoEditorPane({ entityType, entityId, onClose, onSaved }: SeoEdi
     onSaved?.()
   }
 
-  const title = form.metaTitle || record?.title || 'Untitled'
+  const renderedTitle = useMemo(() => {
+    if (!record) return form.metaTitle?.trim() || 'Untitled'
+    return resolveRenderedMetaTitle({
+      metaTitlePage: form.metaTitle,
+      documentTitle: record.title,
+      site: {
+        siteName: record.siteName ?? undefined,
+        titleTemplate: record.titleTemplate ?? undefined,
+      },
+    })
+  }, [form.metaTitle, record])
+
   const desc = form.metaDescription || 'No meta description set. Search engines may generate one.'
   const url = record?.url ?? ''
 
@@ -285,11 +314,11 @@ export function SeoEditorPane({ entityType, entityId, onClose, onSaved }: SeoEdi
 
       <InspectorPaneBody>
         {loading ? (
-          <div className="px-4 py-3.5">
+          <div className="px-5 py-4">
             <SeoLoading />
           </div>
         ) : error ? (
-          <div className="px-4 py-3.5">
+          <div className="px-5 py-4">
             <SeoErrorState message={error} />
           </div>
         ) : record ? (
@@ -297,7 +326,7 @@ export function SeoEditorPane({ entityType, entityId, onClose, onSaved }: SeoEdi
             <InspectorPaneSection title="Google Preview">
               <div className="rounded-[7px] border border-[var(--bdr)] bg-[var(--card)] p-3">
                 <p className="truncate text-[11.5px] text-[var(--suc)]">{url}</p>
-                <p className="text-[15px] leading-snug text-[var(--acc)]">{title}</p>
+                <p className="text-[15px] leading-snug text-[var(--acc)]">{renderedTitle}</p>
                 <p className="line-clamp-2 text-[12px] text-[var(--sub)]">{desc}</p>
               </div>
             </InspectorPaneSection>
@@ -316,7 +345,7 @@ export function SeoEditorPane({ entityType, entityId, onClose, onSaved }: SeoEdi
                   className={inputCls}
                   value={form.metaTitle ?? ''}
                   onChange={(e) => update({ metaTitle: e.target.value })}
-                  placeholder="Page title for search results"
+                  placeholder="Page-specific title (%page% in your site template)"
                 />
               </PaneField>
               <PaneField
@@ -401,10 +430,10 @@ export function SeoEditorPane({ entityType, entityId, onClose, onSaved }: SeoEdi
                     {url.replace(/^https?:\/\//, '').split('/')[0]}
                   </p>
                   <p className="truncate text-[12.5px] font-medium text-[var(--txt)]">
-                    {form.ogTitle || title}
+                    {form.ogTitle || renderedTitle}
                   </p>
                   <p className="line-clamp-1 text-[12px] text-[var(--sub)]">
-                    {form.ogDescription || desc}
+                    {form.ogDescription || form.metaDescription || desc}
                   </p>
                 </div>
               </div>

package/src/components/seo/SeoIssueFixPanel.tsx

@@ -321,7 +321,11 @@ export function SeoIssueFixPanel({
       toast.error(res.error)
       return
     }
-    toast.success('Fix applied and issue resolved.')
+    toast.success(
+      suggestion?.fixStrategy === 'fix-link'
+        ? 'Link updated in content and issue resolved.'
+        : 'Redirect created and issue resolved.',
+    )
     onChanged?.()
   }
 
@@ -408,11 +412,15 @@ export function SeoIssueFixPanel({
                     {suggestion.source === 'ai' && !suggestion.aiUnavailable ? (
                       <span className="bg-primary/10 text-primary inline-flex items-center gap-1 rounded-full px-2.5 py-0.5 text-xs font-medium">
                         <Sparkles className="h-3 w-3" aria-hidden />
-                        AI suggestion
+                        {suggestion.fixStrategy === 'fix-link'
+                          ? 'Fix link in content'
+                          : 'AI suggestion'}
                       </span>
                     ) : suggestion.source === 'deterministic' ? (
                       <span className="bg-muted text-muted-foreground rounded-full px-2.5 py-0.5 text-xs font-medium">
-                        Rule-based fix
+                        {suggestion.fixStrategy === 'fix-link'
+                          ? 'Content link fix'
+                          : 'Rule-based fix'}
                       </span>
                     ) : null}
                   </div>
@@ -483,7 +491,11 @@ export function SeoIssueFixPanel({
                     disabled={busy}
                   >
                     <Check className="h-4 w-4" aria-hidden />
-                    {busy ? 'Applying…' : 'Approve fix'}
+                    {busy
+                      ? 'Applying…'
+                      : suggestion.fixStrategy === 'fix-link'
+                        ? 'Fix link in content'
+                        : 'Approve redirect'}
                   </button>
                 ) : inlineFix && suggestion?.autoFixable && !inlineApplyEnabled ? (
                   <PlanUpgradeCallout feature="seo.inlineApply" upgradeUrl={planInfo?.upgradeUrl} />

package/src/components/seo/primitives.tsx

@@ -153,14 +153,18 @@ export function SectionCard({
           {action}
         </CardHeader>
       )}
-      <CardContent className={title || action ? 'pt-0' : ''}>{children}</CardContent>
+      <CardContent className={title || action ? '' : 'pt-6!'}>{children}</CardContent>
     </Card>
   )
 }
 
 export function SeoLoading({ label = 'Loading…' }: { label?: string }) {
   return (
-    <div className="flex h-64 items-center justify-center" role="status" aria-live="polite">
+    <div
+      className="flex min-h-32 items-center justify-center py-12"
+      role="status"
+      aria-live="polite"
+    >
       <Loader2 className="text-muted-foreground h-6 w-6 animate-spin" aria-hidden />
       <span className="sr-only">{label}</span>
     </div>
@@ -195,7 +199,7 @@ export function SeoEmptyState({
 export function SeoErrorState({ message, onRetry }: { message: string; onRetry?: () => void }) {
   return (
     <div
-      className="border-destructive/30 bg-destructive/5 flex items-center gap-3 rounded-lg border p-3"
+      className="border-destructive/30 bg-destructive/5 flex items-center gap-3 rounded-lg border p-4"
       role="alert"
     >
       <AlertTriangle className="text-destructive h-5 w-5 shrink-0" aria-hidden />

package/src/components/ui/Card.tsx

@@ -10,8 +10,8 @@ const card = cv(
         /** Stat / compact surfaces (`.dstat`). */
         sm: 'px-4 py-3.5',
         /** Simple padded panel (`.dcard-b`). */
-        md: 'px-[18px] py-4',
-        lg: 'px-[18px] py-6',
+        md: 'px-6 py-4',
+        lg: 'px-6 py-6',
       },
       elevation: {
         flat: 'shadow-none',
@@ -55,7 +55,7 @@ export function CardHeader({
 }: HTMLAttributes<HTMLDivElement> & { bordered?: boolean }) {
   return (
     <div
-      className={[bordered ? 'border-b border-[var(--bdr)] px-[18px] py-[14px]' : '', className]
+      className={[bordered ? 'border-b border-[var(--bdr)] px-6 pt-6 pb-4' : '', className]
         .filter(Boolean)
         .join(' ')}
       {...rest}
@@ -96,7 +96,7 @@ export function CardDescription({
 export function CardContent({ className = '', children, ...rest }: HTMLAttributes<HTMLDivElement>) {
   return (
     <div
-      className={`px-[18px] py-4 text-[length:var(--fs-body)] leading-[1.55] text-[var(--sub)] ${className}`}
+      className={`px-6 pt-4 pb-6 text-[length:var(--fs-body)] leading-[1.55] text-[var(--sub)] ${className}`}
       {...rest}
     >
       {children}
@@ -107,7 +107,7 @@ export function CardContent({ className = '', children, ...rest }: HTMLAttribute
 export function CardFooter({ className = '', children, ...rest }: HTMLAttributes<HTMLDivElement>) {
   return (
     <div
-      className={`flex items-center justify-end gap-2 border-t border-[var(--bdr)] px-[18px] py-3 ${className}`}
+      className={`flex items-center justify-end gap-2 border-t border-[var(--bdr)] px-6 py-4 ${className}`}
       {...rest}
     >
       {children}

package/src/components/ui/InspectorPane.tsx

@@ -86,7 +86,7 @@ export function InspectorPaneHeader({
   closeLabel?: string
 }) {
   return (
-    <div className="flex items-start gap-2 border-b border-[var(--bdr)] px-4 py-3.5">
+    <div className="flex items-start gap-2 border-b border-[var(--bdr)] px-5 py-4">
       <div className="min-w-0 flex-1">{children}</div>
       <button
         type="button"
@@ -115,7 +115,7 @@ export function InspectorPaneSection({
   children: ReactNode
 }) {
   return (
-    <div className="border-b border-[var(--bdr)] px-4 py-3.5 last:border-b-0">
+    <div className="border-b border-[var(--bdr)] px-5 py-4 last:border-b-0">
       {title && (
         <div className="mb-2.5 flex items-baseline gap-2">
           <span className="text-[10.5px] font-semibold tracking-[0.6px] text-[var(--muted)] uppercase">
@@ -130,5 +130,5 @@ export function InspectorPaneSection({
 }
 
 export function InspectorPaneFooter({ children }: { children: ReactNode }) {
-  return <div className="border-t border-[var(--bdr)] px-4 py-3.5">{children}</div>
+  return <div className="border-t border-[var(--bdr)] px-5 py-4">{children}</div>
 }

package/src/components/ui/PanelSection.tsx

@@ -0,0 +1,53 @@
+'use client'
+
+import type { ReactNode } from 'react'
+
+/**
+ * Bordered panel with a header divider — Dashboard, modals, and list-heavy views.
+ * Matches Settings/Section card rhythm: `px-6` gutters, `py-4` header, body flush
+ * below the divider with its own padding.
+ */
+export function PanelSection({
+  title,
+  description,
+  action,
+  children,
+  className = '',
+}: {
+  title?: ReactNode
+  description?: ReactNode
+  action?: ReactNode
+  children: ReactNode
+  className?: string
+}) {
+  return (
+    <section
+      className={`bg-card border-border overflow-hidden rounded-xl border shadow-sm ${className}`}
+    >
+      {(title || action) && (
+        <header className="border-border flex items-center justify-between gap-3 border-b px-6 py-4">
+          <div className="min-w-0">
+            {title &&
+              (typeof title === 'string' ? (
+                <h2 className="text-foreground text-sm font-medium">{title}</h2>
+              ) : (
+                title
+              ))}
+            {description &&
+              (typeof description === 'string' ? (
+                <p className="text-muted-foreground mt-0.5 text-xs">{description}</p>
+              ) : (
+                description
+              ))}
+          </div>
+          {action}
+        </header>
+      )}
+      {children}
+    </section>
+  )
+}
+
+/** Standard inset for list rows / table bodies inside a {@link PanelSection}. */
+export const PANEL_LIST_ROW_CLASS =
+  'hover:bg-accent/50 focus-visible:bg-accent/50 w-full px-6 py-4 text-left transition-colors'

package/src/components/ui/ResizableAside.tsx

@@ -0,0 +1,317 @@
+'use client'
+
+import {
+  createContext,
+  useCallback,
+  useContext,
+  useEffect,
+  useRef,
+  useState,
+  type ComponentPropsWithoutRef,
+  type KeyboardEvent,
+  type PointerEvent,
+  type ReactNode,
+} from 'react'
+import { Maximize2, Minimize2 } from 'lucide-react'
+
+export const SECTION_INSPECTOR_WIDTH_KEY = 'actuate:section-inspector-width'
+export const SECTION_INSPECTOR_DEFAULT_WIDTH = 320
+export const SECTION_INSPECTOR_MIN_WIDTH = 280
+export const SECTION_INSPECTOR_MAX_WIDTH = 640
+export const SECTION_INSPECTOR_MIN_CANVAS_WIDTH = 96
+/** Below this editor-row width the expand action uses an overlay panel. */
+export const SECTION_INSPECTOR_OVERLAY_BREAKPOINT = 768
+export const SECTION_INSPECTOR_OVERLAY_MAX_WIDTH = 480
+
+function clampWidth(width: number, max = SECTION_INSPECTOR_MAX_WIDTH): number {
+  return Math.min(max, Math.max(SECTION_INSPECTOR_MIN_WIDTH, width))
+}
+
+/** Max inline width given the surrounding editor row. */
+export function computeInspectorMaxWidth(containerWidth: number): number {
+  if (!Number.isFinite(containerWidth) || containerWidth <= 0) {
+    return SECTION_INSPECTOR_MAX_WIDTH
+  }
+  const containerCap = Math.max(
+    SECTION_INSPECTOR_MIN_WIDTH,
+    containerWidth - SECTION_INSPECTOR_MIN_CANVAS_WIDTH,
+  )
+  return Math.min(SECTION_INSPECTOR_MAX_WIDTH, containerCap)
+}
+
+/** Width when expanded as an overlay on tablet/mobile. */
+export function computeInspectorOverlayWidth(containerWidth: number): number {
+  if (!Number.isFinite(containerWidth) || containerWidth <= 0) {
+    return SECTION_INSPECTOR_OVERLAY_MAX_WIDTH
+  }
+  return Math.min(
+    SECTION_INSPECTOR_OVERLAY_MAX_WIDTH,
+    Math.max(SECTION_INSPECTOR_MIN_WIDTH, containerWidth - 32),
+  )
+}
+
+export function readSectionInspectorWidth(): number {
+  if (typeof window === 'undefined') return SECTION_INSPECTOR_DEFAULT_WIDTH
+  try {
+    const raw = localStorage.getItem(SECTION_INSPECTOR_WIDTH_KEY)
+    if (!raw) return SECTION_INSPECTOR_DEFAULT_WIDTH
+    const parsed = Number.parseInt(raw, 10)
+    if (!Number.isFinite(parsed)) return SECTION_INSPECTOR_DEFAULT_WIDTH
+    return clampWidth(parsed)
+  } catch {
+    return SECTION_INSPECTOR_DEFAULT_WIDTH
+  }
+}
+
+function persistSectionInspectorWidth(width: number, max = SECTION_INSPECTOR_MAX_WIDTH): void {
+  try {
+    localStorage.setItem(SECTION_INSPECTOR_WIDTH_KEY, String(clampWidth(width, max)))
+  } catch {
+    // Storage may be unavailable in private mode.
+  }
+}
+
+interface InspectorResizeContextValue {
+  width: number
+  maxWidth: number
+  isExpanded: boolean
+  canExpand: boolean
+  toggleExpanded: () => void
+}
+
+const InspectorResizeContext = createContext<InspectorResizeContextValue | null>(null)
+
+export function useInspectorResize(): InspectorResizeContextValue | null {
+  return useContext(InspectorResizeContext)
+}
+
+interface ResizableAsideProps extends ComponentPropsWithoutRef<'aside'> {
+  children: ReactNode
+}
+
+/**
+ * Right-hand editor shell with a draggable left edge. Used by the page/post
+ * section inspector and post header panel (default 320px, persisted in
+ * localStorage). On tablet/mobile the handle uses a 44px touch target and
+ * the header expand button can grow the panel to an overlay width.
+ */
+export function ResizableAside({ children, className, style, ...props }: ResizableAsideProps) {
+  const asideRef = useRef<HTMLElement>(null)
+  const [width, setWidth] = useState(SECTION_INSPECTOR_DEFAULT_WIDTH)
+  const [containerWidth, setContainerWidth] = useState(0)
+  const [isExpanded, setIsExpanded] = useState(false)
+  const [dragging, setDragging] = useState(false)
+  const widthRef = useRef(width)
+  const compactWidthRef = useRef(SECTION_INSPECTOR_DEFAULT_WIDTH)
+  const dragRef = useRef<{ startX: number; startWidth: number } | null>(null)
+
+  const inlineMax = computeInspectorMaxWidth(containerWidth)
+  const overlayMax = computeInspectorOverlayWidth(containerWidth)
+  const useOverlay =
+    containerWidth > 0 && containerWidth < SECTION_INSPECTOR_OVERLAY_BREAKPOINT && isExpanded
+  const effectiveMax = useOverlay ? overlayMax : inlineMax
+
+  useEffect(() => {
+    setWidth(readSectionInspectorWidth())
+  }, [])
+
+  useEffect(() => {
+    widthRef.current = width
+  }, [width])
+
+  useEffect(() => {
+    const parent = asideRef.current?.parentElement
+    if (!parent) return
+
+    const update = (nextWidth: number) => {
+      setContainerWidth(nextWidth)
+    }
+
+    update(parent.getBoundingClientRect().width)
+    const observer = new ResizeObserver((entries) => {
+      const entry = entries[0]
+      if (!entry) return
+      update(entry.contentRect.width)
+    })
+    observer.observe(parent)
+    return () => observer.disconnect()
+  }, [])
+
+  useEffect(() => {
+    setWidth((current) => clampWidth(current, effectiveMax))
+  }, [effectiveMax])
+
+  const endDrag = useCallback(() => {
+    dragRef.current = null
+    setDragging(false)
+    document.body.style.cursor = ''
+    document.body.style.userSelect = ''
+    persistSectionInspectorWidth(widthRef.current, inlineMax)
+    if (widthRef.current < effectiveMax - 24) {
+      setIsExpanded(false)
+    }
+  }, [effectiveMax, inlineMax])
+
+  const onPointerDown = useCallback((event: PointerEvent<HTMLDivElement>) => {
+    if (event.button !== 0) return
+    dragRef.current = { startX: event.clientX, startWidth: widthRef.current }
+    setDragging(true)
+    event.currentTarget.setPointerCapture(event.pointerId)
+    document.body.style.cursor = 'col-resize'
+    document.body.style.userSelect = 'none'
+  }, [])
+
+  const onPointerMove = useCallback(
+    (event: PointerEvent<HTMLDivElement>) => {
+      if (!dragRef.current) return
+      const delta = dragRef.current.startX - event.clientX
+      setWidth(clampWidth(dragRef.current.startWidth + delta, effectiveMax))
+    },
+    [effectiveMax],
+  )
+
+  const onPointerUp = useCallback(
+    (event: PointerEvent<HTMLDivElement>) => {
+      if (!dragRef.current) return
+      if (event.currentTarget.hasPointerCapture(event.pointerId)) {
+        event.currentTarget.releasePointerCapture(event.pointerId)
+      }
+      endDrag()
+    },
+    [endDrag],
+  )
+
+  const nudgeWidth = useCallback(
+    (delta: number) => {
+      setWidth((current) => {
+        const next = clampWidth(current + delta, effectiveMax)
+        persistSectionInspectorWidth(next, inlineMax)
+        if (next < effectiveMax - 24) setIsExpanded(false)
+        return next
+      })
+    },
+    [effectiveMax, inlineMax],
+  )
+
+  const onKeyDown = useCallback(
+    (event: KeyboardEvent<HTMLDivElement>) => {
+      if (event.key === 'ArrowLeft') {
+        event.preventDefault()
+        nudgeWidth(16)
+      } else if (event.key === 'ArrowRight') {
+        event.preventDefault()
+        nudgeWidth(-16)
+      } else if (event.key === 'Home') {
+        event.preventDefault()
+        setIsExpanded(false)
+        setWidth(SECTION_INSPECTOR_MIN_WIDTH)
+        persistSectionInspectorWidth(SECTION_INSPECTOR_MIN_WIDTH, inlineMax)
+      } else if (event.key === 'End') {
+        event.preventDefault()
+        setWidth(effectiveMax)
+        persistSectionInspectorWidth(effectiveMax, inlineMax)
+        setIsExpanded(effectiveMax >= inlineMax - 8)
+      }
+    },
+    [effectiveMax, inlineMax, nudgeWidth],
+  )
+
+  const toggleExpanded = useCallback(() => {
+    if (isExpanded) {
+      const restored = clampWidth(compactWidthRef.current, inlineMax)
+      setIsExpanded(false)
+      setWidth(restored)
+      persistSectionInspectorWidth(restored, inlineMax)
+      return
+    }
+
+    compactWidthRef.current = widthRef.current
+    const target =
+      containerWidth > 0 && containerWidth < SECTION_INSPECTOR_OVERLAY_BREAKPOINT
+        ? overlayMax
+        : inlineMax
+    setIsExpanded(true)
+    setWidth(target)
+    persistSectionInspectorWidth(target, inlineMax)
+  }, [containerWidth, inlineMax, isExpanded, overlayMax])
+
+  useEffect(() => {
+    return () => {
+      if (dragRef.current) endDrag()
+    }
+  }, [endDrag])
+
+  const canExpand =
+    !isExpanded &&
+    (containerWidth > 0 && containerWidth < SECTION_INSPECTOR_OVERLAY_BREAKPOINT
+      ? overlayMax > width + 8
+      : inlineMax > width + 8)
+
+  return (
+    <InspectorResizeContext.Provider
+      value={{ width, maxWidth: effectiveMax, isExpanded, canExpand, toggleExpanded }}
+    >
+      <aside
+        {...props}
+        ref={asideRef}
+        data-overlay={useOverlay ? '' : undefined}
+        className={`relative shrink-0 ${useOverlay ? 'absolute top-0 right-0 bottom-0 z-20 shadow-lg' : ''} ${className ?? ''}`}
+        style={{ width, ...style }}
+      >
+        <div
+          role="separator"
+          aria-orientation="vertical"
+          aria-label="Resize inspector panel"
+          aria-valuemin={SECTION_INSPECTOR_MIN_WIDTH}
+          aria-valuemax={effectiveMax}
+          aria-valuenow={width}
+          tabIndex={0}
+          data-dragging={dragging ? '' : undefined}
+          onPointerDown={onPointerDown}
+          onPointerMove={onPointerMove}
+          onPointerUp={onPointerUp}
+          onPointerCancel={onPointerUp}
+          onKeyDown={onKeyDown}
+          className="group absolute inset-y-0 -left-5 z-10 flex w-11 -translate-x-1/2 cursor-col-resize touch-none focus-visible:outline-none md:-left-1 md:w-3 md:translate-x-0"
+        >
+          <div
+            className={`mx-auto h-full w-px motion-safe:transition-colors md:mx-0 ${
+              dragging
+                ? 'bg-primary'
+                : 'bg-border group-hover:bg-primary/50 group-focus-visible:bg-primary/50'
+            }`}
+          />
+        </div>
+        {children}
+      </aside>
+    </InspectorResizeContext.Provider>
+  )
+}
+
+const EXPAND_BUTTON_CLASS =
+  'text-muted-foreground hover:text-foreground hover:bg-accent flex h-9 w-9 items-center justify-center rounded-md transition-colors focus-visible:ring-ring focus-visible:ring-2 focus-visible:outline-none md:h-7 md:w-7'
+
+/** One-tap expand/collapse for tablet and mobile inspector panels. */
+export function InspectorExpandButton({ className }: { className?: string }) {
+  const ctx = useInspectorResize()
+  if (!ctx) return null
+
+  const { isExpanded, canExpand, toggleExpanded } = ctx
+  if (!canExpand && !isExpanded) return null
+
+  return (
+    <button
+      type="button"
+      onClick={toggleExpanded}
+      aria-label={isExpanded ? 'Collapse inspector panel' : 'Expand inspector panel'}
+      aria-pressed={isExpanded}
+      className={className ?? EXPAND_BUTTON_CLASS}
+    >
+      {isExpanded ? (
+        <Minimize2 className="h-4 w-4" aria-hidden />
+      ) : (
+        <Maximize2 className="h-4 w-4" aria-hidden />
+      )}
+    </button>
+  )
+}

package/src/lib/admin-root-element.ts

@@ -0,0 +1,15 @@
+/** Marks the canonical admin shell root (AdminRoot / LoginRoot). */
+export const ADMIN_ROOT_ATTR = 'data-actuate-admin-root'
+
+/**
+ * Resolve the element that owns admin theme tokens (accent, color mode, density).
+ * Prefer the marked shell root so a consumer wrapper `.actuate-admin` does not
+ * steal runtime overrides from the inner AdminRoot.
+ */
+export function getAdminRootElement(): HTMLElement | null {
+  if (typeof document === 'undefined') return null
+  return (
+    document.querySelector<HTMLElement>(`[${ADMIN_ROOT_ATTR}]`) ??
+    document.querySelector<HTMLElement>('.actuate-admin')
+  )
+}

package/src/lib/portal-container.ts

@@ -1,3 +1,5 @@
+import { getAdminRootElement } from './admin-root-element.js'
+
 /**
  * Admin theme tokens are scoped under `.actuate-admin` (styles/theme.css),
  * and dark mode / accent / density are applied as classes-attributes on that
@@ -9,6 +11,5 @@
  * 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
+  return getAdminRootElement() ?? undefined
 }