@bendyline/squisq-editor-react 1.6.1 → 2.0.0

package/src/PreviewControls.tsx

@@ -17,10 +17,12 @@ import {
   useState,
   useMemo,
   useEffect,
+  useId,
   useLayoutEffect,
   useRef,
 } from 'react';
 import type { ReactNode } from 'react';
+import { createPortal } from 'react-dom';
 import type { DisplayMode, CaptionStyle } from '@bendyline/squisq-react';
 import type { ViewportPreset, ViewportConfig } from '@bendyline/squisq/schemas';
 import { VIEWPORT_PRESETS, getThemeSummaries } from '@bendyline/squisq/schemas';
@@ -28,15 +30,23 @@ import type { Theme } from '@bendyline/squisq/schemas';
 import { ThemePicker } from './ThemePicker';
 import { getTransformStyleSummaries } from '@bendyline/squisq/transform';
 import type { Doc } from '@bendyline/squisq/schemas';
-import { setFrontmatterValues } from '@bendyline/squisq/markdown';
+import { readFrontmatterThemeId, setFrontmatterValues } from '@bendyline/squisq/markdown';
 import {
   resolveThemeForDoc,
   writeCustomThemesToFrontmatter,
+  writeCustomTemplatesToFrontmatter,
   FRONTMATTER_CUSTOM_THEMES_KEY,
+  FRONTMATTER_CUSTOM_TEMPLATES_KEY,
 } from '@bendyline/squisq/doc';
 import { useEditorContext } from './EditorContext';
-import { useCustomThemes, CustomThemeDialog, type ThemeSaveTarget } from './customThemes';
+import {
+  useCustomThemes,
+  CustomThemeDialog,
+  type ThemeSaveTarget,
+  type ThemeSaveExtras,
+} from './customThemes';
 import { Icon } from './Icon';
+import { resolvePersistedTransformStyleId } from './transformStyleId';
 
 // ── Context ──────────────────────────────────────────────────────
 
@@ -62,6 +72,10 @@ export interface PreviewSettings {
    *  that style. The single entry point so the toggle buttons persist in one
    *  frontmatter write. */
   setCaptionMode: (mode: CaptionMode) => void;
+  /** Whether Squisq should synthesize and show its managed cover slide. */
+  activeCoverSlide: boolean;
+  /** Enable/disable the managed cover slide. */
+  setCoverSlideEnabled: (enabled: boolean) => void;
   /** User-authored themes (doc + browser library) for the picker's "Custom" group. */
   customThemes: Theme[];
   /** Open the custom-theme designer for a theme (or null to create a new one). */
@@ -77,7 +91,7 @@ export interface PreviewSettings {
 export interface ThemeDesignerConfig {
   value: Theme | null;
   onChange: (theme: Theme) => void;
-  onSave: (theme: Theme, target: ThemeSaveTarget) => void;
+  onSave: (theme: Theme, target: ThemeSaveTarget, extras?: ThemeSaveExtras) => void;
   onClose: () => void;
 }
 
@@ -123,8 +137,9 @@ function resolveRenderAs(value: unknown): ViewportPreset | null {
 function resolveDisplayMode(value: unknown): DisplayMode | null {
   if (typeof value !== 'string') return null;
   const v = value.trim().toLowerCase();
-  if (v === 'video' || v === 'slideshow' || v === 'linear') return v;
+  if (v === 'video' || v === 'slideshow' || v === 'linear' || v === 'narrate') return v;
   if (v === 'slides' || v === 'presentation' || v === 'deck') return 'slideshow';
+  if (v === 'teleprompter' || v === 'prompter') return 'narrate';
   // Frontmatter uses product-facing names: Document is the plain text/HTML
   // preview, Page is the styled Squisq page view. The raw DisplayMode values
   // are older and remain stable for the public React API.
@@ -151,23 +166,21 @@ function resolveFrontmatterTheme(value: unknown, customIds?: Set<string>): strin
   return null;
 }
 
-const VALID_TRANSFORM_IDS = new Set(getTransformStyleSummaries().map((s) => s.id));
-
-function resolveFrontmatterTransform(value: unknown): string | null {
+function resolveFrontmatterCaptionMode(value: unknown): CaptionMode | null {
   if (typeof value !== 'string') return null;
   const v = value.trim().toLowerCase();
-  if (VALID_TRANSFORM_IDS.has(v)) return v;
-  const normalized = v.replace(/\s+/g, '-');
-  if (VALID_TRANSFORM_IDS.has(normalized)) return normalized;
+  if (v === 'off' || v === 'none' || v === 'hidden' || v === 'false' || v === 'no') return 'off';
+  if (v === 'standard' || v === 'cc' || v === 'captions') return 'standard';
+  if (v === 'social' || v === 'instagram' || v === 'tiktok' || v === 'reels') return 'social';
   return null;
 }
 
-function resolveFrontmatterCaptionMode(value: unknown): CaptionMode | null {
+function resolveFrontmatterBoolean(value: unknown): boolean | null {
+  if (typeof value === 'boolean') return value;
   if (typeof value !== 'string') return null;
   const v = value.trim().toLowerCase();
-  if (v === 'off' || v === 'none' || v === 'hidden' || v === 'false' || v === 'no') return 'off';
-  if (v === 'standard' || v === 'cc' || v === 'captions') return 'standard';
-  if (v === 'social' || v === 'instagram' || v === 'tiktok' || v === 'reels') return 'social';
+  if (v === 'true' || v === 'yes' || v === 'on' || v === 'show' || v === 'visible') return true;
+  if (v === 'false' || v === 'no' || v === 'off' || v === 'hide' || v === 'hidden') return false;
   return null;
 }
 
@@ -189,9 +202,10 @@ export interface PreviewSettingsProviderProps {
  *  keys are the canonical names; the legacy keys are still read so existing
  *  documents keep working. Persistence (writes) uses only the squisq names. */
 const FM_KEYS = {
-  theme: { canonical: 'squisq-theme', legacy: 'theme' as const },
+  theme: { canonical: 'squisq-theme', legacy: ['themeId', 'theme'] as const },
   transform: { canonical: 'squisq-transform', legacy: 'transform-style' as const },
   captions: { canonical: 'squisq-captions', legacy: 'caption-style' as const },
+  coverSlide: { canonical: 'squisq-cover-slide', legacy: 'cover-slide' as const },
 } as const;
 
 function readFrontmatterKey(
@@ -209,7 +223,7 @@ export function PreviewSettingsProvider({
   themeOverride,
 }: PreviewSettingsProviderProps) {
   const frontmatter = doc?.frontmatter;
-  const { markdownSource, setMarkdownSource } = useEditorContext();
+  const { markdownSource, setMarkdownSource, allowNarrate } = useEditorContext();
 
   const persistFrontmatter = useCallback(
     (updates: Record<string, string | null>) => {
@@ -231,35 +245,40 @@ export function PreviewSettingsProvider({
   const activePreset = selectedPreset ?? fmPreset ?? 'landscape';
   const activeViewport = VIEWPORT_PRESETS[activePreset];
 
-  // Display mode
+  // Display mode. A frontmatter-forced `narrate` clamps back to video when
+  // the host disabled the mode, so hostile frontmatter can't turn it on.
   const fmMode = useMemo(() => resolveDisplayMode(frontmatter?.['display-mode']), [frontmatter]);
   const [selectedDisplayMode, setSelectedDisplayMode] = useState<DisplayMode | null>(null);
   useEffect(() => setSelectedDisplayMode(null), [fmMode]);
-  const activeDisplayMode = selectedDisplayMode ?? fmMode ?? 'video';
+  const requestedDisplayMode = selectedDisplayMode ?? fmMode ?? 'slideshow';
+  const activeDisplayMode =
+    requestedDisplayMode === 'narrate' && !allowNarrate ? 'video' : requestedDisplayMode;
 
   // Custom themes (doc + browser library). `useCustomThemes` returns null when
-  // no provider is mounted; the picker then just shows built-ins.
+  // no provider is mounted; document-scoped themes still remain available.
   const custom = useCustomThemes();
-  const customThemes = useMemo(() => custom?.allThemes ?? [], [custom]);
+  const docThemes = useMemo(
+    () => custom?.docThemes ?? doc?.customThemes ?? [],
+    [custom, doc?.customThemes],
+  );
+  const customThemes = useMemo(() => custom?.allThemes ?? docThemes, [custom, docThemes]);
   const customIds = useMemo(() => new Set(customThemes.map((t) => t.id)), [customThemes]);
 
-  // Theme — persisted to `squisq-theme` (legacy `theme` still read for compat)
+  // Theme — persisted to `squisq-theme`; `themeId` / `theme` remain readable.
   const fmTheme = useMemo(
-    () =>
-      resolveFrontmatterTheme(
-        readFrontmatterKey(frontmatter, FM_KEYS.theme.canonical, FM_KEYS.theme.legacy),
-        customIds,
-      ),
+    () => resolveFrontmatterTheme(readFrontmatterThemeId(frontmatter), customIds),
     [frontmatter, customIds],
   );
   const [selectedThemeId, setSelectedThemeId] = useState<string | null>(null);
   useEffect(() => setSelectedThemeId(null), [fmTheme]);
   const resolvedThemeId = selectedThemeId ?? fmTheme ?? 'standard';
-  // Doc-scoped resolution: an inline custom theme id resolves from the doc's
-  // own `customThemes` before built-ins — no global registration needed.
+  // Doc themes precede browser-library themes in `allThemes`; choosing a
+  // library-only entry copies it into the document below for portable export.
   const resolvedTheme = useMemo(
-    () => resolveThemeForDoc(doc, resolvedThemeId),
-    [doc, resolvedThemeId],
+    () =>
+      customThemes.find((theme) => theme.id === resolvedThemeId) ??
+      resolveThemeForDoc(doc, resolvedThemeId),
+    [customThemes, doc, resolvedThemeId],
   );
 
   // In-progress theme from the designer dialog; previews live without mutating
@@ -277,9 +296,21 @@ export function PreviewSettingsProvider({
   const handleSetThemeId = useCallback(
     (id: string | null) => {
       setSelectedThemeId(id);
-      if (id !== null) persistFrontmatter({ [FM_KEYS.theme.canonical]: id });
+      if (id === null) return;
+      const selectedCustom = customThemes.find((theme) => theme.id === id);
+      const alreadyDocScoped = docThemes.some((theme) => theme.id === id);
+      const updates: Record<string, string | null> = {
+        [FM_KEYS.theme.canonical]: id,
+        [FM_KEYS.theme.legacy[0]]: null,
+        [FM_KEYS.theme.legacy[1]]: null,
+      };
+      if (selectedCustom && !alreadyDocScoped) {
+        updates[FRONTMATTER_CUSTOM_THEMES_KEY] =
+          writeCustomThemesToFrontmatter([...docThemes, selectedCustom]) ?? null;
+      }
+      persistFrontmatter(updates);
     },
-    [persistFrontmatter],
+    [customThemes, docThemes, persistFrontmatter],
   );
 
   const openThemeDesigner = useCallback((theme: Theme | null) => {
@@ -291,27 +322,38 @@ export function PreviewSettingsProvider({
     setPreviewTheme(null);
   }, []);
   const handleDesignerSave = useCallback(
-    (theme: Theme, target: ThemeSaveTarget) => {
+    (theme: Theme, target: ThemeSaveTarget, extras?: ThemeSaveExtras) => {
       if (target === 'library') {
+        // Imported slide layouts are doc-scoped in v1; the dialog hints at this.
         custom?.upsertLibraryTheme(theme);
       } else {
-        // Write the theme payload AND select it in a SINGLE frontmatter update.
-        // Two separate `setMarkdownSource` calls (upsertDocTheme + a squisq-theme
-        // write) would each derive from the same stale source, so the second
-        // would clobber the first and drop the custom-themes payload.
+        // Write the theme payload, its selection, AND any imported layout
+        // templates in a SINGLE frontmatter update. Separate
+        // `setMarkdownSource` calls would each derive from the same stale
+        // source, so later writes would clobber earlier ones.
         const docThemes = custom?.docThemes ?? [];
         const idx = docThemes.findIndex((t) => t.id === theme.id);
         const nextThemes =
           idx >= 0 ? docThemes.map((t, i) => (i === idx ? theme : t)) : [...docThemes, theme];
-        persistFrontmatter({
+        const updates: Record<string, string | null> = {
           [FRONTMATTER_CUSTOM_THEMES_KEY]: writeCustomThemesToFrontmatter(nextThemes) ?? null,
           [FM_KEYS.theme.canonical]: theme.id,
-        });
+        };
+        if (extras?.templates && extras.templates.length > 0) {
+          const existing = doc?.customTemplates ?? [];
+          const merged = [
+            ...existing.filter((t) => !extras.templates!.some((n) => n.name === t.name)),
+            ...extras.templates,
+          ];
+          updates[FRONTMATTER_CUSTOM_TEMPLATES_KEY] =
+            writeCustomTemplatesToFrontmatter(merged) ?? null;
+        }
+        persistFrontmatter(updates);
         setSelectedThemeId(theme.id);
       }
       closeThemeDesigner();
     },
-    [custom, persistFrontmatter, closeThemeDesigner],
+    [custom, doc, persistFrontmatter, closeThemeDesigner],
   );
   const deleteCustomTheme = useCallback(
     (id: string) => {
@@ -324,7 +366,7 @@ export function PreviewSettingsProvider({
   // Transform — persisted to `squisq-transform` (legacy `transform-style` read for compat)
   const fmTransform = useMemo(
     () =>
-      resolveFrontmatterTransform(
+      resolvePersistedTransformStyleId(
         readFrontmatterKey(frontmatter, FM_KEYS.transform.canonical, FM_KEYS.transform.legacy),
       ),
     [frontmatter],
@@ -366,6 +408,26 @@ export function PreviewSettingsProvider({
     [persistFrontmatter],
   );
 
+  // Managed cover slide — generated from the document startBlock. Defaults on
+  // for existing documents; authors can persist an explicit off switch.
+  const fmCoverSlide = useMemo(
+    () =>
+      resolveFrontmatterBoolean(
+        readFrontmatterKey(frontmatter, FM_KEYS.coverSlide.canonical, FM_KEYS.coverSlide.legacy),
+      ),
+    [frontmatter],
+  );
+  const [selectedCoverSlide, setSelectedCoverSlide] = useState<boolean | null>(null);
+  useEffect(() => setSelectedCoverSlide(null), [fmCoverSlide]);
+  const activeCoverSlide = selectedCoverSlide ?? fmCoverSlide ?? true;
+  const handleSetCoverSlideEnabled = useCallback(
+    (enabled: boolean) => {
+      setSelectedCoverSlide(enabled);
+      persistFrontmatter({ [FM_KEYS.coverSlide.canonical]: enabled ? 'true' : 'false' });
+    },
+    [persistFrontmatter],
+  );
+
   // Config for the docked designer (rendered by `<ThemeDesignerDock>` in the
   // editor content row). Null when closed. setPreviewTheme is a stable setter.
   const themeDesigner = useMemo<ThemeDesignerConfig | null>(
@@ -396,6 +458,8 @@ export function PreviewSettingsProvider({
       activeCaptionStyle,
       activeCaptionsEnabled,
       setCaptionMode: handleSetCaptionMode,
+      activeCoverSlide,
+      setCoverSlideEnabled: handleSetCoverSlideEnabled,
       customThemes,
       openThemeDesigner,
       deleteCustomTheme,
@@ -410,9 +474,11 @@ export function PreviewSettingsProvider({
       activeTransformStyle,
       activeCaptionStyle,
       activeCaptionsEnabled,
+      activeCoverSlide,
       handleSetThemeId,
       handleSetTransformStyle,
       handleSetCaptionMode,
+      handleSetCoverSlideEnabled,
       customThemes,
       openThemeDesigner,
       deleteCustomTheme,
@@ -458,30 +524,80 @@ const FORMAT_SWITCH_OPTIONS: { key: ViewportPreset; label: string; w: number; h:
   { key: 'standard', label: '4:3', w: 12, h: 9 },
 ];
 
-const DISPLAY_MODE_OPTIONS: { key: DisplayMode; label: string }[] = [
-  { key: 'video', label: 'Video' },
-  { key: 'slideshow', label: 'Slideshow' },
-  { key: 'linear', label: 'Page' },
-  { key: 'page', label: 'Document' },
+const DISPLAY_MODE_OPTIONS: {
+  key: DisplayMode;
+  label: string;
+  icon: string;
+  summary: string;
+}[] = [
+  {
+    key: 'slideshow',
+    label: 'Slideshow',
+    icon: 'fa-solid fa-images',
+    summary: 'Present designed slides one at a time.',
+  },
+  {
+    key: 'video',
+    label: 'Video',
+    icon: 'fa-solid fa-circle-play',
+    summary: 'Play an automatically timed presentation.',
+  },
+  {
+    key: 'linear',
+    label: 'Page',
+    icon: 'fa-solid fa-window-maximize',
+    summary: 'Scroll through the fully designed page.',
+  },
+  {
+    key: 'page',
+    label: 'Document',
+    icon: 'fa-solid fa-align-left',
+    summary: 'Read a clean, text-first document.',
+  },
+  {
+    key: 'narrate',
+    label: 'Narrate',
+    icon: 'fa-solid fa-microphone-lines',
+    summary: 'Speak with a voice-paced teleprompter.',
+  },
 ];
 
+export function displayModeLabel(mode: DisplayMode): string {
+  return DISPLAY_MODE_OPTIONS.find((option) => option.key === mode)?.label ?? 'Slideshow';
+}
+
 const TRANSFORM_STYLE_OPTIONS = [
   { key: '', label: 'None' },
   ...getTransformStyleSummaries().map((s) => ({ key: s.id, label: s.name })),
 ];
 
+const SUMMARIZE_TOOLTIP =
+  'Extract and summarize content for presentation with these Use modes. Your underlying content is not changed.';
+
 /**
  * Left-to-right priority order for the preview controls. As the toolbar
  * narrows, controls drop into the overflow menu from the END of this list
- * first (Captions, then Transform, …), so the higher-priority control (Theme)
- * stays inline the longest.
- *
- * Display mode and aspect ratio are not here — they're surfaced separately as
- * the segmented {@link PreviewModeSwitch} / {@link PreviewFormatSwitch} on the
- * left of the toolbar.
+ * first (Cover, then Captions, …). Aspect ratio stays inline the longest, but
+ * still collapses into the same menu when the toolbar is very constrained.
  */
-type ControlKey = 'theme' | 'transform' | 'captions';
-const CONTROL_KEYS: ControlKey[] = ['theme', 'transform', 'captions'];
+type ControlKey = 'format' | 'theme' | 'transform' | 'captions' | 'cover';
+const CONTROL_KEYS: ControlKey[] = ['format', 'theme', 'transform', 'captions', 'cover'];
+
+const PREVIEW_POPOVER_GAP = 4;
+const PREVIEW_POPOVER_MARGIN = 8;
+const PREVIEW_POPOVER_FALLBACK_WIDTH = 220;
+
+function clampPreviewPopoverLeft(
+  triggerRect: DOMRect,
+  popoverWidth: number,
+  viewportWidth: number,
+): number {
+  const maxLeft = Math.max(
+    PREVIEW_POPOVER_MARGIN,
+    viewportWidth - popoverWidth - PREVIEW_POPOVER_MARGIN,
+  );
+  return Math.min(Math.max(PREVIEW_POPOVER_MARGIN, triggerRect.right - popoverWidth), maxLeft);
+}
 
 // ── Shared styles ────────────────────────────────────────────────
 
@@ -510,7 +626,7 @@ const selectStyle: React.CSSProperties = {
  * whole row in and out at a fixed window-width breakpoint, the controls
  * measure how many of them actually fit in the width the toolbar gives them
  * and keep that many inline, folding the rest — from the low-priority end of
- * {@link CONTROL_KEYS} — into a single settings (gear) button's popover. As
+ * {@link CONTROL_KEYS} — into a single ellipsis button's popover. As
  * the toolbar widens or narrows, controls migrate one at a time between the
  * inline row and the menu, so the available space is always well used and the
  * row never wraps onto a second line.
@@ -526,6 +642,27 @@ export function PreviewToolbarControls() {
   // inline and overflow is computed from these per-control measurements.
   const probeRef = useRef<HTMLDivElement>(null);
   const popoverRef = useRef<HTMLDivElement>(null);
+  const popoverTriggerRef = useRef<HTMLButtonElement>(null);
+  const popoverPanelRef = useRef<HTMLDivElement>(null);
+  const [popoverAnchor, setPopoverAnchor] = useState<{ top: number; left: number } | null>(null);
+
+  const updatePopoverPosition = useCallback(() => {
+    const trigger = popoverTriggerRef.current;
+    if (!trigger) return;
+    const triggerRect = trigger.getBoundingClientRect();
+    const measuredWidth =
+      popoverPanelRef.current?.getBoundingClientRect().width ?? PREVIEW_POPOVER_FALLBACK_WIDTH;
+    const popoverWidth = Math.min(measuredWidth, window.innerWidth - PREVIEW_POPOVER_MARGIN * 2);
+    setPopoverAnchor({
+      top: triggerRect.bottom + PREVIEW_POPOVER_GAP,
+      left: clampPreviewPopoverLeft(triggerRect, popoverWidth, window.innerWidth),
+    });
+  }, []);
+
+  const closePopover = useCallback(() => {
+    setPopoverOpen(false);
+    setPopoverAnchor(null);
+  }, []);
 
   // Fit detection: keep as many controls inline as fit, overflow the rest.
   useLayoutEffect(() => {
@@ -534,7 +671,7 @@ export function PreviewToolbarControls() {
     if (!root || !probe) return;
     const GAP = 6; // matches the row's flex `gap`
     const LEAD_PAD = 9; // root's left padding, eaten before any control
-    const GEAR_RESERVE = 40; // width kept for the overflow gear button (+ its gap)
+    const OVERFLOW_TRIGGER_RESERVE = 40; // width kept for the ellipsis button (+ its gap)
     const SAFETY = 2;
     const measure = () => {
       const available = root.clientWidth - LEAD_PAD;
@@ -549,8 +686,8 @@ export function PreviewToolbarControls() {
         setVisibleCount(widths.length);
         return;
       }
-      // Otherwise reserve room for the gear and fit as many as possible.
-      const budget = available - GEAR_RESERVE - GAP - SAFETY;
+      // Otherwise reserve room for the ellipsis and fit as many as possible.
+      const budget = available - OVERFLOW_TRIGGER_RESERVE - GAP - SAFETY;
       let count = 0;
       while (count < widths.length && rowWidth(count + 1) <= budget) count++;
       setVisibleCount(count);
@@ -568,13 +705,29 @@ export function PreviewToolbarControls() {
   useEffect(() => {
     if (!popoverOpen) return;
     const handler = (e: MouseEvent) => {
-      if (popoverRef.current && !popoverRef.current.contains(e.target as Node)) {
-        setPopoverOpen(false);
-      }
+      const target = e.target as Node;
+      if (popoverRef.current?.contains(target)) return;
+      if (popoverPanelRef.current?.contains(target)) return;
+      closePopover();
     };
     document.addEventListener('mousedown', handler);
     return () => document.removeEventListener('mousedown', handler);
-  }, [popoverOpen]);
+  }, [closePopover, popoverOpen]);
+
+  useLayoutEffect(() => {
+    if (!popoverOpen) return;
+    updatePopoverPosition();
+  }, [popoverOpen, updatePopoverPosition, visibleCount]);
+
+  useEffect(() => {
+    if (!popoverOpen) return;
+    window.addEventListener('resize', updatePopoverPosition);
+    window.addEventListener('scroll', updatePopoverPosition, true);
+    return () => {
+      window.removeEventListener('resize', updatePopoverPosition);
+      window.removeEventListener('scroll', updatePopoverPosition, true);
+    };
+  }, [popoverOpen, updatePopoverPosition]);
 
   // "Edit theme" pencil next to the dropdown. A custom theme opens directly in
   // the designer; a built-in seeds a NEW "Modified <name>" custom theme based
@@ -593,6 +746,16 @@ export function PreviewToolbarControls() {
   // label-over-control layout used inside the overflow popover.
   const renderControl = (key: ControlKey, compact: boolean): ReactNode => {
     switch (key) {
+      case 'format':
+        return (
+          <div
+            key="format"
+            className={`squisq-preview-control squisq-preview-control--seg${compact ? ' squisq-preview-control--compact' : ''}`}
+          >
+            {compact && <label style={labelStyle}>Format:</label>}
+            <PreviewFormatSwitch />
+          </div>
+        );
       case 'theme':
         return (
           <div
@@ -639,7 +802,8 @@ export function PreviewToolbarControls() {
         return (
           <PreviewSelect
             key="transform"
-            label="Transform"
+            label="Summarize"
+            labelTooltip={SUMMARIZE_TOOLTIP}
             value={s.activeTransformStyle}
             options={TRANSFORM_STYLE_OPTIONS}
             onChange={(v) => s.setSelectedTransformStyle(v)}
@@ -684,6 +848,22 @@ export function PreviewToolbarControls() {
           </div>
         );
       }
+      case 'cover':
+        return (
+          <div
+            key="cover"
+            className={`squisq-preview-control${compact ? ' squisq-preview-control--compact' : ''}`}
+          >
+            <label className="squisq-preview-checkbox">
+              <input
+                type="checkbox"
+                checked={s.activeCoverSlide}
+                onChange={(e) => s.setCoverSlideEnabled(e.target.checked)}
+              />
+              <span>Cover slide</span>
+            </label>
+          </div>
+        );
     }
   };
 
@@ -691,10 +871,18 @@ export function PreviewToolbarControls() {
   const visibleKeys = CONTROL_KEYS.slice(0, visibleCount);
   const overflowKeys = CONTROL_KEYS.slice(visibleCount);
 
+  useEffect(() => {
+    if (!hasOverflow && popoverOpen) closePopover();
+  }, [closePopover, hasOverflow, popoverOpen]);
+
   // The root is a flex:1 filler so it always spans the toolbar's leftover
   // width (which is what the fit measurement reads).
   return (
-    <div className="squisq-preview-controls" ref={rootRef}>
+    <div
+      className="squisq-preview-controls"
+      data-has-overflow={hasOverflow ? 'true' : undefined}
+      ref={rootRef}
+    >
       {/* Hidden probe — every control at natural width, measured to decide the
           inline/overflow split. Absolutely positioned so it never affects
           layout. */}
@@ -702,35 +890,37 @@ export function PreviewToolbarControls() {
         {CONTROL_KEYS.map((key) => renderControl(key, false))}
       </div>
 
-      <div className="squisq-preview-controls-inline">
-        {visibleKeys.map((key) => renderControl(key, false))}
-      </div>
+      {visibleKeys.length > 0 && (
+        <div className="squisq-preview-controls-inline">
+          {visibleKeys.map((key) => renderControl(key, false))}
+        </div>
+      )}
 
       {hasOverflow && (
         <div className="squisq-preview-controls-compact" ref={popoverRef}>
           <button
+            ref={popoverTriggerRef}
             className={`squisq-toolbar-button${popoverOpen ? ' squisq-toolbar-button--active' : ''}`}
-            onClick={() => setPopoverOpen((v) => !v)}
+            onClick={() => {
+              if (popoverOpen) {
+                closePopover();
+                return;
+              }
+              updatePopoverPosition();
+              setPopoverOpen(true);
+            }}
             aria-label="More preview settings"
             title="More preview settings"
             aria-expanded={popoverOpen}
           >
-            <svg
-              width="16"
-              height="16"
-              viewBox="0 0 16 16"
-              fill="none"
-              stroke="currentColor"
-              strokeWidth="1.5"
-              strokeLinecap="round"
-              strokeLinejoin="round"
-            >
-              <circle cx="8" cy="8" r="2.5" />
-              <path d="M13.5 8a5.5 5.5 0 01-.4 1.8l1.2 1.2-1.6 1.6-1.2-1.2A5.5 5.5 0 018 13.5a5.5 5.5 0 01-3.5-1.3L3.3 13.4 1.7 11.8l1.2-1.2A5.5 5.5 0 012.5 8c0-.6.1-1.2.4-1.8L1.7 5 3.3 3.4l1.2 1.2A5.5 5.5 0 018 2.5c1.3 0 2.5.5 3.5 1.3l1.2-1.2 1.6 1.6-1.2 1.2c.3.6.4 1.2.4 1.6z" />
-            </svg>
+            <Icon icon="fa-solid fa-ellipsis" />
           </button>
-          {popoverOpen && (
-            <div className="squisq-preview-controls-popover">
+          {popoverOpen && popoverAnchor && (
+            <div
+              ref={popoverPanelRef}
+              className="squisq-preview-controls-popover"
+              style={{ top: popoverAnchor.top, left: popoverAnchor.left }}
+            >
               {overflowKeys.map((key) => renderControl(key, true))}
             </div>
           )}
@@ -741,16 +931,17 @@ export function PreviewToolbarControls() {
 }
 
 /**
- * Segmented display-mode switch (Video / Slideshow / Document / Page) rendered
- * as four connected buttons on the left of the Play toolbar — the prominent,
- * one-click counterpart to the old "Mode:" dropdown. Reads and writes the same
- * `activeDisplayMode` in preview settings.
+ * Segmented display-mode switch retained as a public, embeddable control.
+ * The editor shell uses {@link PreviewModeMenu} beside its Use tab instead.
+ * Narrate is hidden when the host disables `allowNarrate`.
  */
 export function PreviewModeSwitch() {
   const s = usePreviewSettings();
+  const { allowNarrate } = useEditorContext();
+  const options = DISPLAY_MODE_OPTIONS.filter((opt) => opt.key !== 'narrate' || allowNarrate);
   return (
     <div className="squisq-preview-seg" role="group" aria-label="Display mode">
-      {DISPLAY_MODE_OPTIONS.map((opt) => {
+      {options.map((opt) => {
         const active = s.activeDisplayMode === opt.key;
         return (
           <button
@@ -768,6 +959,185 @@ export function PreviewModeSwitch() {
   );
 }
 
+const USE_MODE_MENU_WIDTH = 340;
+const USE_MODE_MENU_GAP = 4;
+const USE_MODE_MENU_MARGIN = 8;
+
+/**
+ * Dropdown trigger rendered directly beside the Use tab. Selecting a mode
+ * also enters the Use view, so the menu works from Write and Source as well
+ * as from an already-active preview.
+ */
+export interface PreviewModeMenuProps {
+  /** Incremented by the parent to open the menu from another control. */
+  openRequest?: number;
+}
+
+export function PreviewModeMenu({ openRequest = 0 }: PreviewModeMenuProps) {
+  const s = usePreviewSettings();
+  const { allowNarrate, colorScheme, setActiveView } = useEditorContext();
+  const options = DISPLAY_MODE_OPTIONS.filter((opt) => opt.key !== 'narrate' || allowNarrate);
+  const activeLabel = displayModeLabel(s.activeDisplayMode);
+  const triggerRef = useRef<HTMLButtonElement>(null);
+  const menuRef = useRef<HTMLDivElement>(null);
+  const itemIdPrefix = useId();
+  const [open, setOpen] = useState(false);
+  const [anchor, setAnchor] = useState<{ top: number; left: number } | null>(null);
+
+  const updatePosition = useCallback(() => {
+    const trigger = triggerRef.current;
+    if (!trigger) return;
+    const rect = trigger.getBoundingClientRect();
+    const menuWidth = Math.min(USE_MODE_MENU_WIDTH, window.innerWidth - USE_MODE_MENU_MARGIN * 2);
+    const maxLeft = Math.max(
+      USE_MODE_MENU_MARGIN,
+      window.innerWidth - menuWidth - USE_MODE_MENU_MARGIN,
+    );
+    setAnchor({
+      top: rect.bottom + USE_MODE_MENU_GAP,
+      left: Math.min(Math.max(USE_MODE_MENU_MARGIN, rect.right - menuWidth), maxLeft),
+    });
+  }, []);
+
+  const closeMenu = useCallback((restoreFocus = false) => {
+    setOpen(false);
+    setAnchor(null);
+    if (restoreFocus) triggerRef.current?.focus();
+  }, []);
+
+  const openMenu = useCallback(() => {
+    updatePosition();
+    setOpen(true);
+  }, [updatePosition]);
+
+  useEffect(() => {
+    if (openRequest > 0) openMenu();
+  }, [openMenu, openRequest]);
+
+  useEffect(() => {
+    if (!open) return;
+    const handlePointerDown = (event: MouseEvent) => {
+      const target = event.target as Node;
+      if (triggerRef.current?.contains(target) || menuRef.current?.contains(target)) return;
+      closeMenu();
+    };
+    const handleKeyDown = (event: KeyboardEvent) => {
+      if (event.key !== 'Escape') return;
+      event.preventDefault();
+      closeMenu(true);
+    };
+    document.addEventListener('mousedown', handlePointerDown);
+    document.addEventListener('keydown', handleKeyDown);
+    window.addEventListener('resize', updatePosition);
+    window.addEventListener('scroll', updatePosition, true);
+    return () => {
+      document.removeEventListener('mousedown', handlePointerDown);
+      document.removeEventListener('keydown', handleKeyDown);
+      window.removeEventListener('resize', updatePosition);
+      window.removeEventListener('scroll', updatePosition, true);
+    };
+  }, [closeMenu, open, updatePosition]);
+
+  useLayoutEffect(() => {
+    if (!open || !anchor) return;
+    const selected = menuRef.current?.querySelector<HTMLButtonElement>('[aria-checked="true"]');
+    const first = menuRef.current?.querySelector<HTMLButtonElement>('[role="menuitemradio"]');
+    (selected ?? first)?.focus();
+  }, [anchor, open]);
+
+  return (
+    <>
+      <button
+        ref={triggerRef}
+        type="button"
+        className={`squisq-use-mode-trigger${open ? ' squisq-use-mode-trigger--open' : ''}`}
+        aria-label="Choose Use mode"
+        aria-haspopup="menu"
+        aria-expanded={open}
+        title={`Use mode: ${activeLabel}`}
+        onClick={() => (open ? closeMenu() : openMenu())}
+        onKeyDown={(event) => {
+          if (event.key !== 'ArrowDown') return;
+          event.preventDefault();
+          openMenu();
+        }}
+      >
+        <svg width="10" height="10" viewBox="0 0 10 10" aria-hidden="true">
+          <path d="M2 3.5 5 6.5 8 3.5" fill="none" stroke="currentColor" strokeWidth="1.4" />
+        </svg>
+      </button>
+      {open &&
+        anchor &&
+        createPortal(
+          <div
+            ref={menuRef}
+            className="squisq-use-mode-menu"
+            data-theme={colorScheme}
+            role="menu"
+            aria-label="Use mode"
+            style={{ top: anchor.top, left: anchor.left }}
+            onKeyDown={(event) => {
+              if (!['ArrowDown', 'ArrowUp', 'Home', 'End'].includes(event.key)) return;
+              event.preventDefault();
+              const items = Array.from(
+                event.currentTarget.querySelectorAll<HTMLButtonElement>('[role="menuitemradio"]'),
+              );
+              if (items.length === 0) return;
+              const currentIndex = items.indexOf(document.activeElement as HTMLButtonElement);
+              const nextIndex =
+                event.key === 'Home'
+                  ? 0
+                  : event.key === 'End'
+                    ? items.length - 1
+                    : event.key === 'ArrowUp'
+                      ? (currentIndex - 1 + items.length) % items.length
+                      : (currentIndex + 1) % items.length;
+              items[nextIndex]?.focus();
+            }}
+          >
+            {options.map((option) => {
+              const selected = option.key === s.activeDisplayMode;
+              const labelId = `${itemIdPrefix}-${option.key}-label`;
+              const summaryId = `${itemIdPrefix}-${option.key}-summary`;
+              return (
+                <button
+                  key={option.key}
+                  type="button"
+                  className={`squisq-use-mode-menu-item${selected ? ' squisq-use-mode-menu-item--selected' : ''}`}
+                  role="menuitemradio"
+                  aria-checked={selected}
+                  aria-labelledby={labelId}
+                  aria-describedby={summaryId}
+                  onClick={() => {
+                    s.setSelectedDisplayMode(option.key);
+                    setActiveView('preview');
+                    closeMenu(true);
+                  }}
+                >
+                  <span className="squisq-use-mode-menu-icon" aria-hidden="true">
+                    <Icon icon={option.icon} />
+                  </span>
+                  <span className="squisq-use-mode-menu-copy">
+                    <span id={labelId} className="squisq-use-mode-menu-label">
+                      {option.label}
+                    </span>
+                    <span id={summaryId} className="squisq-use-mode-menu-summary">
+                      {option.summary}
+                    </span>
+                  </span>
+                  <span className="squisq-use-mode-menu-check" aria-hidden="true">
+                    {selected && <Icon icon="fa-solid fa-check" />}
+                  </span>
+                </button>
+              );
+            })}
+          </div>,
+          document.body,
+        )}
+    </>
+  );
+}
+
 /** A simple aspect-ratio glyph: a centered rounded rectangle of `w`×`h` in a
  *  16×16 box, so 16:9 reads as a wide box, 1:1 a square, 9:16 a tall box. */
 function AspectIcon({ w, h }: { w: number; h: number }) {
@@ -787,10 +1157,9 @@ function AspectIcon({ w, h }: { w: number; h: number }) {
 }
 
 /**
- * Segmented aspect-ratio switch (16:9 / 1:1 / 9:16 / 4:3) rendered as connected
- * icon buttons on the left of the Play toolbar, next to the mode switch — the
- * one-click counterpart to the old "Format:" dropdown. Reads and writes the
- * same `activePreset` in preview settings.
+ * Segmented aspect-ratio switch (16:9 / 1:1 / 9:16 / 4:3), used inline in the
+ * Use toolbar and inside its overflow popover. Reads and writes the same
+ * `activePreset` in preview settings.
  */
 export function PreviewFormatSwitch() {
   const s = usePreviewSettings();
@@ -818,12 +1187,14 @@ export function PreviewFormatSwitch() {
 
 function PreviewSelect({
   label,
+  labelTooltip,
   value,
   options,
   onChange,
   compact,
 }: {
   label: string;
+  labelTooltip?: string;
   value: string;
   options: { key: string; label: string }[];
   onChange: (value: string) => void;
@@ -831,7 +1202,9 @@ function PreviewSelect({
 }) {
   return (
     <div className={`squisq-preview-control${compact ? ' squisq-preview-control--compact' : ''}`}>
-      <label style={labelStyle}>{label}:</label>
+      <label style={labelStyle} title={labelTooltip}>
+        {label}:
+      </label>
       <select value={value} onChange={(e) => onChange(e.target.value)} style={selectStyle}>
         {options.map((o) => (
           <option key={o.key} value={o.key}>