@bendyline/squisq-editor-react 1.6.1 → 2.0.0

package/src/__tests__/presentationMode.test.tsx

@@ -0,0 +1,290 @@
+/**
+ * @vitest-environment jsdom
+ */
+
+import { useRef } from 'react';
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { cleanup, fireEvent, render, screen, waitFor, within } from '@testing-library/react';
+import { EditorProvider } from '../EditorContext';
+import {
+  PresentationModeControl,
+  PresentationModeProvider,
+} from '../presentation/PresentationMode';
+
+function Harness() {
+  const rootRef = useRef<HTMLDivElement>(null);
+  return (
+    <div ref={rootRef} data-testid="shell">
+      <PresentationModeProvider rootRef={rootRef}>
+        <PresentationModeControl />
+        <div data-testid="content">Preview</div>
+      </PresentationModeProvider>
+    </div>
+  );
+}
+
+function renderHarness() {
+  return render(
+    <EditorProvider initialMarkdown="# Presentation" initialView="preview">
+      <Harness />
+    </EditorProvider>,
+  );
+}
+
+afterEach(() => {
+  cleanup();
+  vi.restoreAllMocks();
+});
+
+describe('PresentationModeControl', () => {
+  it('chooses the launch behavior from an accessible radio menu', () => {
+    renderHarness();
+
+    expect(screen.getByRole('button', { name: 'Present: Fill Squisq' })).toBeTruthy();
+    fireEvent.click(screen.getByRole('button', { name: 'Presentation options' }));
+
+    const menu = screen.getByRole('menu', { name: 'Presentation options' });
+    const items = within(menu).getAllByRole('menuitemradio');
+    expect(items.map((item) => item.textContent)).toEqual([
+      'Fill SquisqUse the entire Squisq control.',
+      'New windowOpen an audience view synced to this one.',
+      'Browser full screenBrowser full screen is unavailable.',
+    ]);
+    expect(items[0].getAttribute('aria-checked')).toBe('true');
+    expect(items.map((item) => item.tabIndex)).toEqual([0, -1, -1]);
+
+    fireEvent.keyDown(items[0], { key: 'ArrowDown' });
+    expect(document.activeElement).toBe(items[1]);
+    const tabEvent = new KeyboardEvent('keydown', {
+      key: 'Tab',
+      bubbles: true,
+      cancelable: true,
+    });
+    fireEvent(items[1], tabEvent);
+    expect(tabEvent.defaultPrevented).toBe(true);
+    expect(screen.queryByRole('menu', { name: 'Presentation options' })).toBeNull();
+    expect(document.activeElement).toBe(
+      screen.getByRole('button', { name: 'Presentation options' }),
+    );
+
+    fireEvent.click(screen.getByRole('button', { name: 'Presentation options' }));
+    const reopenedMenu = screen.getByRole('menu', { name: 'Presentation options' });
+
+    fireEvent.click(within(reopenedMenu).getByRole('menuitemradio', { name: /New window/ }));
+    expect(screen.getByRole('button', { name: 'Present: New window' })).toBeTruthy();
+    expect(screen.queryByRole('menu', { name: 'Presentation options' })).toBeNull();
+  });
+
+  it('fills only the Squisq shell and exits on Escape', async () => {
+    renderHarness();
+    const shell = screen.getByTestId('shell');
+    const launchButton = screen.getByRole('button', { name: 'Present: Fill Squisq' });
+
+    launchButton.focus();
+    fireEvent.click(launchButton);
+    expect(shell.getAttribute('data-presentation-mode')).toBe('control');
+    const exitButton = screen.getByRole('button', { name: 'Exit presentation mode' });
+    expect(document.activeElement).toBe(exitButton);
+
+    fireEvent.keyDown(document, { key: 'Escape' });
+    await waitFor(() => expect(shell.hasAttribute('data-presentation-mode')).toBe(false));
+    expect(screen.getByRole('button', { name: 'Present: Fill Squisq' })).toBeTruthy();
+    expect(document.activeElement).toBe(launchButton);
+  });
+
+  it('tracks native fullscreen exit from the browser', async () => {
+    const originalRequest = Object.getOwnPropertyDescriptor(
+      HTMLElement.prototype,
+      'requestFullscreen',
+    );
+    const originalExit = Object.getOwnPropertyDescriptor(document, 'exitFullscreen');
+    const originalElement = Object.getOwnPropertyDescriptor(document, 'fullscreenElement');
+    let fullscreenElement: Element | null = null;
+    const requestFullscreen = vi.fn(() => Promise.resolve());
+    Object.defineProperty(HTMLElement.prototype, 'requestFullscreen', {
+      configurable: true,
+      value: requestFullscreen,
+    });
+    Object.defineProperty(document, 'exitFullscreen', {
+      configurable: true,
+      value: vi.fn(async () => {
+        fullscreenElement = null;
+      }),
+    });
+    Object.defineProperty(document, 'fullscreenElement', {
+      configurable: true,
+      get: () => fullscreenElement,
+    });
+
+    try {
+      renderHarness();
+      fireEvent.click(screen.getByRole('button', { name: 'Presentation options' }));
+      fireEvent.click(
+        screen.getByRole('menuitemradio', { name: /Browser full screen.*Use the browser/ }),
+      );
+      fireEvent.click(screen.getByRole('button', { name: 'Present: Browser full screen' }));
+
+      const shell = screen.getByTestId('shell');
+      await waitFor(() => expect(requestFullscreen).toHaveBeenCalledWith());
+      await waitFor(() => expect(shell.getAttribute('data-presentation-mode')).toBe('fullscreen'));
+
+      fullscreenElement = null;
+      fireEvent(document, new Event('fullscreenchange'));
+      await waitFor(() => expect(shell.hasAttribute('data-presentation-mode')).toBe(false));
+    } finally {
+      if (originalRequest) {
+        Object.defineProperty(HTMLElement.prototype, 'requestFullscreen', originalRequest);
+      } else {
+        Reflect.deleteProperty(HTMLElement.prototype, 'requestFullscreen');
+      }
+      if (originalExit) Object.defineProperty(document, 'exitFullscreen', originalExit);
+      else Reflect.deleteProperty(document, 'exitFullscreen');
+      if (originalElement) Object.defineProperty(document, 'fullscreenElement', originalElement);
+      else Reflect.deleteProperty(document, 'fullscreenElement');
+    }
+  });
+
+  it('keeps fullscreen presentation active when browser exit is rejected', async () => {
+    const originalRequest = Object.getOwnPropertyDescriptor(
+      HTMLElement.prototype,
+      'requestFullscreen',
+    );
+    const originalExit = Object.getOwnPropertyDescriptor(document, 'exitFullscreen');
+    const originalElement = Object.getOwnPropertyDescriptor(document, 'fullscreenElement');
+    let fullscreenElement: Element | null = null;
+    let requestedRoot: Element | null = null;
+    Object.defineProperty(HTMLElement.prototype, 'requestFullscreen', {
+      configurable: true,
+      value: vi.fn(async () => {
+        fullscreenElement = requestedRoot;
+      }),
+    });
+    Object.defineProperty(document, 'exitFullscreen', {
+      configurable: true,
+      value: vi.fn(async () => {
+        throw new Error('exit denied');
+      }),
+    });
+    Object.defineProperty(document, 'fullscreenElement', {
+      configurable: true,
+      get: () => fullscreenElement,
+    });
+
+    try {
+      renderHarness();
+      requestedRoot = screen.getByTestId('shell');
+      fireEvent.click(screen.getByRole('button', { name: 'Presentation options' }));
+      fireEvent.click(screen.getByRole('menuitemradio', { name: /Browser full screen/ }));
+      fireEvent.click(screen.getByRole('button', { name: 'Present: Browser full screen' }));
+      await waitFor(() =>
+        expect(screen.getByTestId('shell').getAttribute('data-presentation-mode')).toBe(
+          'fullscreen',
+        ),
+      );
+
+      fireEvent.click(screen.getByRole('button', { name: 'Stop presentation' }));
+      await waitFor(() =>
+        expect(screen.getByRole('alert').textContent).toContain('could not exit full screen'),
+      );
+      expect(screen.getByTestId('shell').getAttribute('data-presentation-mode')).toBe('fullscreen');
+
+      fullscreenElement = null;
+      fireEvent(document, new Event('fullscreenchange'));
+    } finally {
+      if (originalRequest) {
+        Object.defineProperty(HTMLElement.prototype, 'requestFullscreen', originalRequest);
+      } else {
+        Reflect.deleteProperty(HTMLElement.prototype, 'requestFullscreen');
+      }
+      if (originalExit) Object.defineProperty(document, 'exitFullscreen', originalExit);
+      else Reflect.deleteProperty(document, 'exitFullscreen');
+      if (originalElement) Object.defineProperty(document, 'fullscreenElement', originalElement);
+      else Reflect.deleteProperty(document, 'fullscreenElement');
+    }
+  });
+
+  it('opens a same-origin audience window and cleans up when it closes', async () => {
+    const popupDocument = document.implementation.createHTMLDocument('');
+    const popupEvents = new EventTarget();
+    let closed = false;
+    const popup = {
+      document: popupDocument,
+      get closed() {
+        return closed;
+      },
+      close: vi.fn(() => {
+        closed = true;
+      }),
+      focus: vi.fn(),
+      addEventListener: popupEvents.addEventListener.bind(popupEvents),
+      removeEventListener: popupEvents.removeEventListener.bind(popupEvents),
+    } as unknown as Window;
+    vi.spyOn(window, 'open').mockReturnValue(popup);
+
+    renderHarness();
+    fireEvent.click(screen.getByRole('button', { name: 'Presentation options' }));
+    fireEvent.click(screen.getByRole('menuitemradio', { name: /New window/ }));
+    fireEvent.click(screen.getByRole('button', { name: 'Present: New window' }));
+
+    const shell = screen.getByTestId('shell');
+    await waitFor(() => expect(shell.getAttribute('data-presentation-mode')).toBe('window'));
+    expect(popupDocument.querySelector('#squisq-presentation-root')).toBeTruthy();
+    expect(popupDocument.querySelector('[aria-label="Exit presentation mode"]')).toBeTruthy();
+
+    // Re-selecting the checked destination only closes the menu; it must not
+    // tear down the active audience window.
+    fireEvent.click(screen.getByRole('button', { name: 'Presentation options' }));
+    fireEvent.click(screen.getByRole('menuitemradio', { name: /New window/ }));
+    expect(shell.getAttribute('data-presentation-mode')).toBe('window');
+    expect(popup.close).not.toHaveBeenCalled();
+
+    popupEvents.dispatchEvent(new Event('pagehide'));
+    await waitFor(() => expect(shell.hasAttribute('data-presentation-mode')).toBe(false));
+  });
+
+  it('reports a blocked audience window without entering presentation', async () => {
+    vi.spyOn(window, 'open').mockReturnValue(null);
+    renderHarness();
+    fireEvent.click(screen.getByRole('button', { name: 'Presentation options' }));
+    fireEvent.click(screen.getByRole('menuitemradio', { name: /New window/ }));
+    fireEvent.click(screen.getByRole('button', { name: 'Present: New window' }));
+
+    await waitFor(() =>
+      expect(screen.getByRole('alert').textContent).toContain('presentation window was blocked'),
+    );
+    expect(screen.getByTestId('shell').hasAttribute('data-presentation-mode')).toBe(false);
+  });
+
+  it('cleans up when popup initialization fails after the portal is prepared', async () => {
+    const popupDocument = document.implementation.createHTMLDocument('');
+    const popupEvents = new EventTarget();
+    let closed = false;
+    const popup = {
+      document: popupDocument,
+      get closed() {
+        return closed;
+      },
+      close: vi.fn(() => {
+        closed = true;
+      }),
+      focus: vi.fn(() => {
+        throw new Error('focus failed');
+      }),
+      addEventListener: popupEvents.addEventListener.bind(popupEvents),
+      removeEventListener: popupEvents.removeEventListener.bind(popupEvents),
+    } as unknown as Window;
+    vi.spyOn(window, 'open').mockReturnValue(popup);
+
+    renderHarness();
+    fireEvent.click(screen.getByRole('button', { name: 'Presentation options' }));
+    fireEvent.click(screen.getByRole('menuitemradio', { name: /New window/ }));
+    fireEvent.click(screen.getByRole('button', { name: 'Present: New window' }));
+
+    await waitFor(() =>
+      expect(screen.getByRole('alert').textContent).toContain('presentation window was blocked'),
+    );
+    expect(screen.getByTestId('shell').hasAttribute('data-presentation-mode')).toBe(false);
+    expect(popup.close).toHaveBeenCalledOnce();
+    expect(popupDocument.querySelector('[aria-label="Exit presentation mode"]')).toBeNull();
+  });
+});

package/src/__tests__/previewControls.test.tsx

@@ -2,13 +2,34 @@
  * @vitest-environment jsdom
  */
 import { afterEach, describe, expect, it } from 'vitest';
-import { cleanup, fireEvent, render, screen, waitFor } from '@testing-library/react';
+import { cleanup, fireEvent, render, screen, waitFor, within } from '@testing-library/react';
+import { compileTheme } from '@bendyline/squisq/schemas';
 import { EditorProvider, useEditorContext } from '../EditorContext';
-import { PreviewModeSwitch, PreviewSettingsProvider, usePreviewSettings } from '../PreviewControls';
+import {
+  PreviewModeSwitch,
+  PreviewSettingsProvider,
+  PreviewToolbarControls,
+  usePreviewSettings,
+} from '../PreviewControls';
+import { Toolbar } from '../Toolbar';
+import {
+  clearThemeLibrary,
+  CustomThemeProvider,
+  saveLibraryTheme,
+  useDocCustomThemes,
+} from '../customThemes';
 
 function ModeProbe() {
-  const { activeDisplayMode } = usePreviewSettings();
-  return <div data-testid="active-mode">{activeDisplayMode}</div>;
+  const { activeDisplayMode, activeThemeId, activeTransformStyle } = usePreviewSettings();
+  return (
+    <div
+      data-testid="active-mode"
+      data-theme-id={activeThemeId}
+      data-transform-style={activeTransformStyle}
+    >
+      {activeDisplayMode}
+    </div>
+  );
 }
 
 function PreviewHarness() {
@@ -21,6 +42,52 @@ function PreviewHarness() {
   );
 }
 
+function PreviewToolbarHarness() {
+  const { doc } = useEditorContext();
+  return (
+    <PreviewSettingsProvider doc={doc}>
+      <PreviewToolbarControls />
+    </PreviewSettingsProvider>
+  );
+}
+
+function UseTabHarness() {
+  const { activeView, doc } = useEditorContext();
+  return (
+    <PreviewSettingsProvider doc={doc}>
+      <Toolbar />
+      <ModeProbe />
+      <div data-testid="active-view">{activeView}</div>
+    </PreviewSettingsProvider>
+  );
+}
+
+function LibraryThemeProbe() {
+  const { activeTheme, setSelectedThemeId } = usePreviewSettings();
+  const { markdownSource } = useEditorContext();
+  return (
+    <>
+      <button type="button" onClick={() => setSelectedThemeId('library-theme')}>
+        Select library theme
+      </button>
+      <div data-testid="active-theme-name">{activeTheme.name}</div>
+      <pre data-testid="markdown-source">{markdownSource}</pre>
+    </>
+  );
+}
+
+function LibraryThemeHarness() {
+  const { doc } = useEditorContext();
+  const { docThemes, onDocThemesChange } = useDocCustomThemes();
+  return (
+    <CustomThemeProvider docThemes={docThemes} onDocThemesChange={onDocThemesChange}>
+      <PreviewSettingsProvider doc={doc}>
+        <LibraryThemeProbe />
+      </PreviewSettingsProvider>
+    </CustomThemeProvider>
+  );
+}
+
 function renderPreviewControls(markdown: string) {
   render(
     <EditorProvider initialMarkdown={markdown}>
@@ -29,7 +96,18 @@ function renderPreviewControls(markdown: string) {
   );
 }
 
-afterEach(() => cleanup());
+function renderPreviewToolbar(markdown: string) {
+  render(
+    <EditorProvider initialMarkdown={markdown}>
+      <PreviewToolbarHarness />
+    </EditorProvider>,
+  );
+}
+
+afterEach(() => {
+  cleanup();
+  clearThemeLibrary();
+});
 
 describe('PreviewModeSwitch', () => {
   it('labels the plain document preview as Document and the styled view as Page', () => {
@@ -40,7 +118,8 @@ describe('PreviewModeSwitch', () => {
       .map((button) => button.textContent)
       .filter(Boolean);
 
-    expect(labels).toEqual(['Video', 'Slideshow', 'Page', 'Document']);
+    expect(labels).toEqual(['Slideshow', 'Video', 'Page', 'Document', 'Narrate']);
+    expect(screen.getByTestId('active-mode').textContent).toBe('slideshow');
 
     fireEvent.click(screen.getByRole('button', { name: 'Document' }));
     expect(screen.getByTestId('active-mode').textContent).toBe('page');
@@ -67,4 +146,231 @@ describe('PreviewModeSwitch', () => {
     });
     expect(screen.getByRole('button', { name: 'Page' }).getAttribute('aria-pressed')).toBe('true');
   });
+
+  it('uses the shared squisq-theme, themeId, theme fallback order', async () => {
+    renderPreviewControls('---\nthemeId: bold\ntheme: cinematic\n---\n\n# Hello');
+
+    await waitFor(() => {
+      expect(screen.getByTestId('active-mode').getAttribute('data-theme-id')).toBe('bold');
+    });
+  });
+
+  it('canonicalizes the stored dataDriven transform id', async () => {
+    renderPreviewControls('---\nsquisq-transform: dataDriven\n---\n\n# Hello');
+
+    await waitFor(() => {
+      expect(screen.getByTestId('active-mode').getAttribute('data-transform-style')).toBe(
+        'data-driven',
+      );
+    });
+  });
+
+  it('copies a selected browser-library theme into the document atomically', async () => {
+    saveLibraryTheme(
+      compileTheme({
+        id: 'library-theme',
+        name: 'Library Theme',
+        seedColors: { primary: '#456789' },
+      }),
+    );
+    render(
+      <EditorProvider initialMarkdown="# Hello">
+        <LibraryThemeHarness />
+      </EditorProvider>,
+    );
+
+    fireEvent.click(screen.getByRole('button', { name: 'Select library theme' }));
+
+    await waitFor(() => {
+      expect(screen.getByTestId('active-theme-name').textContent).toBe('Library Theme');
+      const source = screen.getByTestId('markdown-source').textContent ?? '';
+      expect(source).toContain('squisq-theme: library-theme');
+      expect(source).toContain('squisq-custom-themes:');
+      expect(source).toContain('library-theme');
+    });
+  });
+});
+
+describe('PreviewToolbarControls', () => {
+  it('presents transforms as summarization without implying the source is changed', () => {
+    const originalResizeObserver = globalThis.ResizeObserver;
+    class ResizeObserverStub implements ResizeObserver {
+      observe() {}
+      unobserve() {}
+      disconnect() {}
+    }
+
+    globalThis.ResizeObserver = ResizeObserverStub;
+    try {
+      renderPreviewToolbar('# Hello');
+
+      const summarizeLabels = screen.getAllByText('Summarize:');
+      expect(summarizeLabels.length).toBeGreaterThan(0);
+      for (const label of summarizeLabels) {
+        expect(label.getAttribute('title')).toBe(
+          'Extract and summarize content for presentation with these Use modes. Your underlying content is not changed.',
+        );
+      }
+      expect(screen.queryByText('Transform:')).toBeNull();
+      expect(document.querySelector('[role="group"][aria-label="Display mode"]')).toBeNull();
+      expect(document.querySelector('[role="group"][aria-label="Aspect ratio"]')).not.toBeNull();
+    } finally {
+      if (originalResizeObserver) {
+        globalThis.ResizeObserver = originalResizeObserver;
+      } else {
+        Reflect.deleteProperty(globalThis, 'ResizeObserver');
+      }
+    }
+  });
+
+  it('keeps the overflow popover inside the left viewport edge', async () => {
+    const originalResizeObserver = globalThis.ResizeObserver;
+    const originalGetBoundingClientRect = HTMLElement.prototype.getBoundingClientRect;
+    const originalClientWidth = Object.getOwnPropertyDescriptor(
+      HTMLElement.prototype,
+      'clientWidth',
+    );
+
+    class ResizeObserverStub implements ResizeObserver {
+      readonly callback: ResizeObserverCallback;
+
+      constructor(callback: ResizeObserverCallback) {
+        this.callback = callback;
+      }
+
+      observe() {
+        this.callback([], this);
+      }
+
+      unobserve() {}
+
+      disconnect() {}
+    }
+
+    globalThis.ResizeObserver = ResizeObserverStub;
+    HTMLElement.prototype.getBoundingClientRect = function getBoundingClientRect() {
+      if (this.classList.contains('squisq-preview-controls-popover')) {
+        return new DOMRect(0, 0, 220, 240);
+      }
+      if (this.getAttribute('aria-label') === 'More preview settings') {
+        return new DOMRect(6, 20, 28, 28);
+      }
+      if (this.classList.contains('squisq-preview-control')) {
+        return new DOMRect(0, 0, 100, 24);
+      }
+      return new DOMRect(0, 0, 0, 0);
+    };
+    Object.defineProperty(HTMLElement.prototype, 'clientWidth', {
+      configurable: true,
+      get() {
+        return this.classList.contains('squisq-preview-controls') ? 40 : 0;
+      },
+    });
+
+    try {
+      renderPreviewToolbar('# Hello');
+
+      fireEvent.click(await screen.findByRole('button', { name: 'More preview settings' }));
+
+      await waitFor(() => {
+        const popover = document.querySelector<HTMLElement>('.squisq-preview-controls-popover');
+        expect(popover).not.toBeNull();
+        expect(popover?.style.left).toBe('8px');
+      });
+    } finally {
+      if (originalResizeObserver) {
+        globalThis.ResizeObserver = originalResizeObserver;
+      } else {
+        Reflect.deleteProperty(globalThis, 'ResizeObserver');
+      }
+      HTMLElement.prototype.getBoundingClientRect = originalGetBoundingClientRect;
+      if (originalClientWidth) {
+        Object.defineProperty(HTMLElement.prototype, 'clientWidth', originalClientWidth);
+      } else {
+        Reflect.deleteProperty(HTMLElement.prototype, 'clientWidth');
+      }
+    }
+  });
+});
+
+describe('Use tab mode menu', () => {
+  it('lists the Use modes beside the tab and selects a mode without a toolbar radio group', () => {
+    render(
+      <EditorProvider initialMarkdown="# Hello" initialView="wysiwyg" allowRecording={false}>
+        <UseTabHarness />
+      </EditorProvider>,
+    );
+
+    const useTab = screen.getByRole('tab', { name: 'Slideshow' });
+    expect(screen.queryByRole('tab', { name: 'Use' })).toBeNull();
+    const tabGroup = useTab.parentElement;
+    expect(tabGroup).not.toBeNull();
+    expect(within(tabGroup!).getByRole('button', { name: 'Choose Use mode' })).toBeTruthy();
+
+    // The first click enters Use; once active, clicking the tab again opens
+    // the mode menu.
+    fireEvent.click(useTab);
+    expect(screen.getByTestId('active-view').textContent).toBe('preview');
+    expect(screen.queryByRole('menu', { name: 'Use mode' })).toBeNull();
+
+    fireEvent.click(screen.getByRole('tab', { name: 'Slideshow' }));
+
+    const menu = screen.getByRole('menu', { name: 'Use mode' });
+    expect(
+      within(menu)
+        .getAllByRole('menuitemradio')
+        .map((item) => item.querySelector('.squisq-use-mode-menu-label')?.textContent),
+    ).toEqual(['Slideshow', 'Video', 'Page', 'Document', 'Narrate']);
+    const slideshowItem = within(menu).getByRole('menuitemradio', { name: 'Slideshow' });
+    expect(slideshowItem.getAttribute('aria-checked')).toBe('true');
+    expect(within(slideshowItem).getByText('Present designed slides one at a time.')).toBeTruthy();
+
+    fireEvent.click(within(menu).getByRole('menuitemradio', { name: 'Document' }));
+    expect(screen.getByTestId('active-mode').textContent).toBe('page');
+    expect(screen.getByTestId('active-view').textContent).toBe('preview');
+    expect(screen.getByRole('tab', { name: 'Document' })).toBeTruthy();
+    expect(screen.queryByRole('menu', { name: 'Use mode' })).toBeNull();
+  });
+});
+
+describe('Narrate mode gating', () => {
+  function renderWithNarrateGate(markdown: string, allowNarrate: boolean) {
+    render(
+      <EditorProvider initialMarkdown={markdown} allowNarrate={allowNarrate}>
+        <PreviewHarness />
+      </EditorProvider>,
+    );
+  }
+
+  it('selects narrate from the switch and resolves teleprompter frontmatter aliases', async () => {
+    renderPreviewControls('# Hello');
+    fireEvent.click(screen.getByRole('button', { name: 'Narrate' }));
+    expect(screen.getByTestId('active-mode').textContent).toBe('narrate');
+
+    cleanup();
+    renderPreviewControls('---\ndisplay-mode: teleprompter\n---\n\n# Hello');
+    await waitFor(() => {
+      expect(screen.getByTestId('active-mode').textContent).toBe('narrate');
+    });
+    expect(screen.getByRole('button', { name: 'Narrate' }).getAttribute('aria-pressed')).toBe(
+      'true',
+    );
+  });
+
+  it('allowNarrate=false hides the button and clamps frontmatter-forced narrate to video', async () => {
+    renderWithNarrateGate('---\ndisplay-mode: narrate\n---\n\n# Hello', false);
+
+    expect(screen.queryByRole('button', { name: 'Narrate' })).toBeNull();
+    // Give the frontmatter parse a tick, then confirm the clamp held.
+    await waitFor(() => {
+      expect(screen.getByTestId('active-mode').textContent).toBe('video');
+    });
+  });
+
+  it('allowNarrate=true (default) honors frontmatter narrate', async () => {
+    renderWithNarrateGate('---\ndisplay-mode: narrate\n---\n\n# Hello', true);
+    await waitFor(() => {
+      expect(screen.getByTestId('active-mode').textContent).toBe('narrate');
+    });
+  });
 });

package/src/__tests__/previewPanelAudioFailure.test.tsx

@@ -0,0 +1,46 @@
+/** @vitest-environment jsdom */
+import { render, screen, waitFor } from '@testing-library/react';
+import { describe, expect, it, vi } from 'vitest';
+import { MemoryContentContainer } from '@bendyline/squisq/storage';
+
+const resolveAudioMapping = vi.hoisted(() =>
+  vi.fn(async () => {
+    throw new Error('timing.json is corrupt');
+  }),
+);
+
+vi.mock('@bendyline/squisq/doc', async (importOriginal) => ({
+  ...(await importOriginal<typeof import('@bendyline/squisq/doc')>()),
+  resolveAudioMapping,
+}));
+
+import { EditorProvider, useEditorContext } from '../EditorContext';
+import { PreviewSettingsProvider } from '../PreviewControls';
+import { PreviewPanel } from '../PreviewPanel';
+
+function Harness({ container }: { container: MemoryContentContainer }) {
+  const { doc } = useEditorContext();
+  return (
+    <PreviewSettingsProvider doc={doc}>
+      <PreviewPanel workspaceContainer={container} />
+    </PreviewSettingsProvider>
+  );
+}
+
+describe('PreviewPanel optional audio mapping', () => {
+  it('keeps the synchronous preview when audio discovery rejects', async () => {
+    const load = vi.spyOn(HTMLMediaElement.prototype, 'load').mockImplementation(() => undefined);
+    const container = new MemoryContentContainer();
+    const view = render(
+      <EditorProvider initialMarkdown="# Preview\n\nBody" initialView="preview">
+        <Harness container={container} />
+      </EditorProvider>,
+    );
+    await waitFor(() => expect(resolveAudioMapping).toHaveBeenCalled());
+    await waitFor(() => {
+      expect(screen.getByTestId('preview-panel').textContent).not.toContain('No content');
+    });
+    view.unmount();
+    load.mockRestore();
+  });
+});