@bendyline/squisq-editor-react 1.6.2 → 2.0.1

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,28 @@ 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';
+import {
+  FRONTMATTER_SETTING_DEFAULTS,
+  FRONTMATTER_SETTING_KEYS,
+  omitFrontmatterDefault,
+} from './frontmatterSettings';
 
 // ── Context ──────────────────────────────────────────────────────
 
@@ -81,7 +96,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;
 }
 
@@ -127,8 +142,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.
@@ -155,17 +171,6 @@ 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 {
-  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;
-  return null;
-}
-
 function resolveFrontmatterCaptionMode(value: unknown): CaptionMode | null {
   if (typeof value !== 'string') return null;
   const v = value.trim().toLowerCase();
@@ -198,16 +203,6 @@ export interface PreviewSettingsProviderProps {
   themeOverride?: Theme | null;
 }
 
-/** Frontmatter keys we read/write for preview settings. The squisq-prefixed
- *  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 },
-  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(
   fm: Record<string, unknown> | undefined,
   canonical: string,
@@ -223,10 +218,10 @@ 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>) => {
+    (updates: Record<string, string | number | boolean | null | undefined>) => {
       const next = setFrontmatterValues(markdownSource, updates);
       if (next !== markdownSource) {
         setMarkdownSource(next);
@@ -245,35 +240,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.
+  const resolvedThemeId = selectedThemeId ?? fmTheme ?? FRONTMATTER_SETTING_DEFAULTS.theme;
+  // 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
@@ -291,9 +291,24 @@ 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> = {
+        [FRONTMATTER_SETTING_KEYS.theme.canonical]: omitFrontmatterDefault(
+          id,
+          FRONTMATTER_SETTING_DEFAULTS.theme,
+        ),
+        [FRONTMATTER_SETTING_KEYS.theme.legacy[0]]: null,
+        [FRONTMATTER_SETTING_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) => {
@@ -305,27 +320,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,
-        });
+          [FRONTMATTER_SETTING_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) => {
@@ -338,8 +364,12 @@ export function PreviewSettingsProvider({
   // Transform — persisted to `squisq-transform` (legacy `transform-style` read for compat)
   const fmTransform = useMemo(
     () =>
-      resolveFrontmatterTransform(
-        readFrontmatterKey(frontmatter, FM_KEYS.transform.canonical, FM_KEYS.transform.legacy),
+      resolvePersistedTransformStyleId(
+        readFrontmatterKey(
+          frontmatter,
+          FRONTMATTER_SETTING_KEYS.transform.canonical,
+          FRONTMATTER_SETTING_KEYS.transform.legacy,
+        ),
       ),
     [frontmatter],
   );
@@ -351,7 +381,13 @@ export function PreviewSettingsProvider({
       setSelectedTransformStyle(id);
       if (id !== null) {
         // Empty string = "None" — remove the key rather than writing a blank value.
-        persistFrontmatter({ [FM_KEYS.transform.canonical]: id === '' ? null : id });
+        persistFrontmatter({
+          [FRONTMATTER_SETTING_KEYS.transform.canonical]: omitFrontmatterDefault(
+            id,
+            FRONTMATTER_SETTING_DEFAULTS.transform,
+          ),
+          [FRONTMATTER_SETTING_KEYS.transform.legacy]: null,
+        });
       }
     },
     [persistFrontmatter],
@@ -363,19 +399,30 @@ export function PreviewSettingsProvider({
   const fmCaptionMode = useMemo(
     () =>
       resolveFrontmatterCaptionMode(
-        readFrontmatterKey(frontmatter, FM_KEYS.captions.canonical, FM_KEYS.captions.legacy),
+        readFrontmatterKey(
+          frontmatter,
+          FRONTMATTER_SETTING_KEYS.captions.canonical,
+          FRONTMATTER_SETTING_KEYS.captions.legacy,
+        ),
       ),
     [frontmatter],
   );
   const [selectedCaptionMode, setSelectedCaptionMode] = useState<CaptionMode | null>(null);
   useEffect(() => setSelectedCaptionMode(null), [fmCaptionMode]);
-  const activeCaptionMode = selectedCaptionMode ?? fmCaptionMode ?? 'standard';
+  const activeCaptionMode =
+    selectedCaptionMode ?? fmCaptionMode ?? FRONTMATTER_SETTING_DEFAULTS.captions;
   const activeCaptionsEnabled = activeCaptionMode !== 'off';
   const activeCaptionStyle: CaptionStyle = activeCaptionMode === 'social' ? 'social' : 'standard';
   const handleSetCaptionMode = useCallback(
     (mode: CaptionMode) => {
       setSelectedCaptionMode(mode);
-      persistFrontmatter({ [FM_KEYS.captions.canonical]: mode });
+      persistFrontmatter({
+        [FRONTMATTER_SETTING_KEYS.captions.canonical]: omitFrontmatterDefault(
+          mode,
+          FRONTMATTER_SETTING_DEFAULTS.captions,
+        ),
+        [FRONTMATTER_SETTING_KEYS.captions.legacy]: null,
+      });
     },
     [persistFrontmatter],
   );
@@ -385,17 +432,31 @@ export function PreviewSettingsProvider({
   const fmCoverSlide = useMemo(
     () =>
       resolveFrontmatterBoolean(
-        readFrontmatterKey(frontmatter, FM_KEYS.coverSlide.canonical, FM_KEYS.coverSlide.legacy),
+        readFrontmatterKey(
+          frontmatter,
+          FRONTMATTER_SETTING_KEYS.coverSlide.canonical,
+          FRONTMATTER_SETTING_KEYS.coverSlide.legacy,
+        ),
       ),
     [frontmatter],
   );
   const [selectedCoverSlide, setSelectedCoverSlide] = useState<boolean | null>(null);
   useEffect(() => setSelectedCoverSlide(null), [fmCoverSlide]);
-  const activeCoverSlide = selectedCoverSlide ?? fmCoverSlide ?? true;
+  const activeCoverSlide =
+    selectedCoverSlide ?? fmCoverSlide ?? FRONTMATTER_SETTING_DEFAULTS.coverSlide;
   const handleSetCoverSlideEnabled = useCallback(
     (enabled: boolean) => {
       setSelectedCoverSlide(enabled);
-      persistFrontmatter({ [FM_KEYS.coverSlide.canonical]: enabled ? 'true' : 'false' });
+      persistFrontmatter({
+        // The cover is enabled by default, so only persist the non-default
+        // state. Pass the boolean through so YAML writes `false`, not
+        // the string `"false"`.
+        [FRONTMATTER_SETTING_KEYS.coverSlide.canonical]: omitFrontmatterDefault(
+          enabled,
+          FRONTMATTER_SETTING_DEFAULTS.coverSlide,
+        ),
+        [FRONTMATTER_SETTING_KEYS.coverSlide.legacy]: null,
+      });
     },
     [persistFrontmatter],
   );
@@ -496,27 +557,64 @@ 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 (Cover, then Captions, …). Display mode and aspect ratio stay inline
- * the longest, but still collapse into the same menu when the toolbar is very
- * constrained.
+ * 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 = 'mode' | 'format' | 'theme' | 'transform' | 'captions' | 'cover';
-const CONTROL_KEYS: ControlKey[] = ['mode', 'format', 'theme', 'transform', 'captions', 'cover'];
+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;
@@ -681,16 +779,6 @@ export function PreviewToolbarControls() {
   // label-over-control layout used inside the overflow popover.
   const renderControl = (key: ControlKey, compact: boolean): ReactNode => {
     switch (key) {
-      case 'mode':
-        return (
-          <div
-            key="mode"
-            className={`squisq-preview-control squisq-preview-control--seg${compact ? ' squisq-preview-control--compact' : ''}`}
-          >
-            {compact && <label style={labelStyle}>Mode:</label>}
-            <PreviewModeSwitch />
-          </div>
-        );
       case 'format':
         return (
           <div
@@ -747,7 +835,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)}
@@ -798,7 +887,6 @@ export function PreviewToolbarControls() {
             key="cover"
             className={`squisq-preview-control${compact ? ' squisq-preview-control--compact' : ''}`}
           >
-            <label style={labelStyle}>Cover:</label>
             <label className="squisq-preview-checkbox">
               <input
                 type="checkbox"
@@ -876,15 +964,17 @@ export function PreviewToolbarControls() {
 }
 
 /**
- * Segmented display-mode switch (Video / Slideshow / Document / Page), used
- * inline in the Use toolbar and inside its overflow popover. 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
@@ -902,6 +992,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 }) {
@@ -951,12 +1220,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;
@@ -964,7 +1235,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}>