@bendyline/squisq-react 1.3.1 → 1.4.0

package/src/MarkdownRenderer.tsx

@@ -15,14 +15,17 @@
  */
 
 import { Fragment } from 'react';
-import type {
+import {
+  sanitizeHtmlNodes,
+  sanitizeUrl,
+  type HtmlPolicy,
+  type HtmlElement,
+  type HtmlNode,
   MarkdownBlockNode,
   MarkdownInlineNode,
   MarkdownListItem,
   MarkdownTableRow,
   MarkdownTableCell,
-  HtmlNode,
-  HtmlElement,
 } from '@bendyline/squisq/markdown';
 import { useMediaUrl } from './hooks/MediaContext';
 import { InlineVideoPlayer } from './InlineVideoPlayer.js';
@@ -35,12 +38,21 @@ export interface MarkdownRendererProps {
   nodes: MarkdownBlockNode[];
   /** Optional CSS class for the wrapper element */
   className?: string;
+  /**
+   * Raw HTML policy. Defaults to `sanitize`, which removes unsafe tags,
+   * event handlers, and executable URL schemes before rendering.
+   */
+  htmlPolicy?: HtmlPolicy;
 }
 
 // ── Inline Renderer ────────────────────────────────────────────────
 
 /** Render an array of inline nodes into React elements. */
-function renderInline(nodes: MarkdownInlineNode[], keyPrefix = ''): React.ReactNode[] {
+function renderInline(
+  nodes: MarkdownInlineNode[],
+  keyPrefix = '',
+  htmlPolicy: HtmlPolicy = 'sanitize',
+): React.ReactNode[] {
   return nodes.map((node, i) => {
     const key = `${keyPrefix}i${i}`;
     switch (node.type) {
@@ -67,21 +79,21 @@ function renderInline(nodes: MarkdownInlineNode[], keyPrefix = ''): React.ReactN
       case 'emphasis':
         return (
           <em key={key} className="squisq-md-em">
-            {renderInline(node.children, key)}
+            {renderInline(node.children, key, htmlPolicy)}
           </em>
         );
 
       case 'strong':
         return (
           <strong key={key} className="squisq-md-strong">
-            {renderInline(node.children, key)}
+            {renderInline(node.children, key, htmlPolicy)}
           </strong>
         );
 
       case 'delete':
         return (
           <del key={key} className="squisq-md-del">
-            {renderInline(node.children, key)}
+            {renderInline(node.children, key, htmlPolicy)}
           </del>
         );
 
@@ -92,19 +104,28 @@ function renderInline(nodes: MarkdownInlineNode[], keyPrefix = ''): React.ReactN
           </code>
         );
 
-      case 'link':
+      case 'link': {
+        const href = sanitizeUrl(node.url, 'link');
+        if (!href) {
+          return (
+            <span key={key} className="squisq-md-link squisq-md-link--blocked">
+              {renderInline(node.children, key, htmlPolicy)}
+            </span>
+          );
+        }
         return (
           <a
             key={key}
             className="squisq-md-link"
-            href={node.url}
+            href={href}
             title={node.title ?? undefined}
             target="_blank"
             rel="noopener noreferrer"
           >
-            {renderInline(node.children, key)}
+            {renderInline(node.children, key, htmlPolicy)}
           </a>
         );
+      }
 
       case 'image':
         return (
@@ -122,9 +143,15 @@ function renderInline(nodes: MarkdownInlineNode[], keyPrefix = ''): React.ReactN
         );
 
       case 'htmlInline':
+        if (htmlPolicy === 'strip') return null;
         // Fast path: no <video>/<audio> in the subtree → use the original
         // rawHtml passthrough (preserves arbitrary HTML for custom embeds).
-        if (!containsMediaTag(node.htmlChildren)) {
+        if (
+          htmlPolicy === 'trusted' &&
+          !containsMediaTag(node.htmlChildren) &&
+          !containsDangerousTag(node.htmlChildren) &&
+          !hasDangerousRawHtml(node.rawHtml)
+        ) {
           return (
             <span
               key={key}
@@ -137,7 +164,7 @@ function renderInline(nodes: MarkdownInlineNode[], keyPrefix = ''): React.ReactN
         // go through MediaContext-aware player components.
         return (
           <span key={key} className="squisq-md-html-inline">
-            {renderHtmlNodes(node.htmlChildren, `${key}h`)}
+            {renderHtmlNodes(resolveHtmlNodes(node.htmlChildren, htmlPolicy), `${key}h`)}
           </span>
         );
 
@@ -152,7 +179,7 @@ function renderInline(nodes: MarkdownInlineNode[], keyPrefix = ''): React.ReactN
         // Render as plain text (definition targets not available at render time)
         return (
           <span key={key} className="squisq-md-link-ref">
-            {renderInline(node.children, key)}
+            {renderInline(node.children, key, htmlPolicy)}
           </span>
         );
 
@@ -166,7 +193,7 @@ function renderInline(nodes: MarkdownInlineNode[], keyPrefix = ''): React.ReactN
       case 'textDirective':
         return (
           <span key={key} className="squisq-md-text-directive" data-directive={node.name}>
-            {renderInline(node.children, key)}
+            {renderInline(node.children, key, htmlPolicy)}
           </span>
         );
 
@@ -193,12 +220,16 @@ function renderInline(nodes: MarkdownInlineNode[], keyPrefix = ''): React.ReactN
 // ── Block Renderer ─────────────────────────────────────────────────
 
 /** Render a single block-level node into a React element. */
-function renderBlock(node: MarkdownBlockNode, key: string): React.ReactNode {
+function renderBlock(
+  node: MarkdownBlockNode,
+  key: string,
+  htmlPolicy: HtmlPolicy = 'sanitize',
+): React.ReactNode {
   switch (node.type) {
     case 'paragraph':
       return (
         <p key={key} className="squisq-md-p">
-          {renderInline(node.children, key)}
+          {renderInline(node.children, key, htmlPolicy)}
         </p>
       );
 
@@ -206,7 +237,7 @@ function renderBlock(node: MarkdownBlockNode, key: string): React.ReactNode {
       const Tag = `h${node.depth}` as 'h1' | 'h2' | 'h3' | 'h4' | 'h5' | 'h6';
       return (
         <Tag key={key} className={`squisq-md-heading squisq-md-h${node.depth}`}>
-          {renderInline(node.children, key)}
+          {renderInline(node.children, key, htmlPolicy)}
         </Tag>
       );
     }
@@ -214,7 +245,7 @@ function renderBlock(node: MarkdownBlockNode, key: string): React.ReactNode {
     case 'blockquote':
       return (
         <blockquote key={key} className="squisq-md-blockquote">
-          {renderBlocks(node.children, key)}
+          {renderBlocks(node.children, key, htmlPolicy)}
         </blockquote>
       );
 
@@ -222,13 +253,13 @@ function renderBlock(node: MarkdownBlockNode, key: string): React.ReactNode {
       if (node.ordered) {
         return (
           <ol key={key} className="squisq-md-list squisq-md-ol" start={node.start ?? undefined}>
-            {node.children.map((item, i) => renderListItem(item, `${key}li${i}`))}
+            {node.children.map((item, i) => renderListItem(item, `${key}li${i}`, htmlPolicy))}
           </ol>
         );
       }
       return (
         <ul key={key} className="squisq-md-list squisq-md-ul">
-          {node.children.map((item, i) => renderListItem(item, `${key}li${i}`))}
+          {node.children.map((item, i) => renderListItem(item, `${key}li${i}`, htmlPolicy))}
         </ul>
       );
 
@@ -243,12 +274,18 @@ function renderBlock(node: MarkdownBlockNode, key: string): React.ReactNode {
       return <hr key={key} className="squisq-md-hr" />;
 
     case 'table':
-      return renderTable(node.children, node.align, key);
+      return renderTable(node.children, node.align, key, htmlPolicy);
 
     case 'htmlBlock':
+      if (htmlPolicy === 'strip') return null;
       // Fast path: no <video>/<audio> → preserve the existing rawHtml
       // passthrough so arbitrary HTML embeds still survive verbatim.
-      if (!containsMediaTag(node.htmlChildren)) {
+      if (
+        htmlPolicy === 'trusted' &&
+        !containsMediaTag(node.htmlChildren) &&
+        !containsDangerousTag(node.htmlChildren) &&
+        !hasDangerousRawHtml(node.rawHtml)
+      ) {
         return (
           <div
             key={key}
@@ -261,7 +298,7 @@ function renderBlock(node: MarkdownBlockNode, key: string): React.ReactNode {
       // route through the player components and resolve via MediaContext.
       return (
         <div key={key} className="squisq-md-html-block">
-          {renderHtmlNodes(node.htmlChildren, `${key}h`)}
+          {renderHtmlNodes(resolveHtmlNodes(node.htmlChildren, htmlPolicy), `${key}h`)}
         </div>
       );
 
@@ -280,7 +317,7 @@ function renderBlock(node: MarkdownBlockNode, key: string): React.ReactNode {
       return (
         <div key={key} className="squisq-md-footnote-def" id={`fn-${node.identifier}`}>
           <sup>{node.label ?? node.identifier}</sup>
-          {renderBlocks(node.children, key)}
+          {renderBlocks(node.children, key, htmlPolicy)}
         </div>
       );
 
@@ -292,7 +329,7 @@ function renderBlock(node: MarkdownBlockNode, key: string): React.ReactNode {
           data-directive={node.name}
         >
           {node.label && <div className="squisq-md-directive-label">{node.label}</div>}
-          {renderBlocks(node.children, key)}
+          {renderBlocks(node.children, key, htmlPolicy)}
         </div>
       );
 
@@ -303,7 +340,7 @@ function renderBlock(node: MarkdownBlockNode, key: string): React.ReactNode {
           className={`squisq-md-directive squisq-md-directive-${node.name}`}
           data-directive={node.name}
         >
-          {renderInline(node.children, key)}
+          {renderInline(node.children, key, htmlPolicy)}
         </div>
       );
 
@@ -314,13 +351,13 @@ function renderBlock(node: MarkdownBlockNode, key: string): React.ReactNode {
             if (child.type === 'definitionTerm') {
               return (
                 <dt key={`${key}dt${i}`} className="squisq-md-dt">
-                  {renderInline(child.children, `${key}dt${i}`)}
+                  {renderInline(child.children, `${key}dt${i}`, htmlPolicy)}
                 </dt>
               );
             }
             return (
               <dd key={`${key}dd${i}`} className="squisq-md-dd">
-                {renderBlocks(child.children, `${key}dd${i}`)}
+                {renderBlocks(child.children, `${key}dd${i}`, htmlPolicy)}
               </dd>
             );
           })}
@@ -333,14 +370,18 @@ function renderBlock(node: MarkdownBlockNode, key: string): React.ReactNode {
 }
 
 /** Render a list item, including task-list checkbox support. */
-function renderListItem(item: MarkdownListItem, key: string): React.ReactNode {
+function renderListItem(
+  item: MarkdownListItem,
+  key: string,
+  htmlPolicy: HtmlPolicy = 'sanitize',
+): React.ReactNode {
   const isTask = item.checked !== null && item.checked !== undefined;
   return (
     <li key={key} className={`squisq-md-li${isTask ? ' squisq-md-task' : ''}`}>
       {isTask && (
         <input type="checkbox" checked={!!item.checked} readOnly className="squisq-md-checkbox" />
       )}
-      {renderBlocks(item.children, key)}
+      {renderBlocks(item.children, key, htmlPolicy)}
     </li>
   );
 }
@@ -350,6 +391,7 @@ function renderTable(
   rows: MarkdownTableRow[],
   align: (('left' | 'right' | 'center') | null)[] | undefined,
   key: string,
+  htmlPolicy: HtmlPolicy = 'sanitize',
 ): React.ReactNode {
   const [headerRow, ...bodyRows] = rows;
   return (
@@ -363,7 +405,7 @@ function renderTable(
                 className="squisq-md-th"
                 style={align?.[ci] ? { textAlign: align[ci]! } : undefined}
               >
-                {renderInline(cell.children, `${key}th${ci}`)}
+                {renderInline(cell.children, `${key}th${ci}`, htmlPolicy)}
               </th>
             ))}
           </tr>
@@ -379,7 +421,7 @@ function renderTable(
                   className="squisq-md-td"
                   style={align?.[ci] ? { textAlign: align[ci]! } : undefined}
                 >
-                  {renderInline(cell.children, `${key}td${ri}-${ci}`)}
+                  {renderInline(cell.children, `${key}td${ri}-${ci}`, htmlPolicy)}
                 </td>
               ))}
             </tr>
@@ -391,15 +433,21 @@ function renderTable(
 }
 
 /** Render an array of block-level nodes. */
-function renderBlocks(nodes: MarkdownBlockNode[], keyPrefix = ''): React.ReactNode[] {
-  return nodes.map((node, i) => renderBlock(node, `${keyPrefix}b${i}`));
+function renderBlocks(
+  nodes: MarkdownBlockNode[],
+  keyPrefix = '',
+  htmlPolicy: HtmlPolicy = 'sanitize',
+): React.ReactNode[] {
+  return nodes.map((node, i) => renderBlock(node, `${keyPrefix}b${i}`, htmlPolicy));
 }
 
 // ── Image with MediaProvider resolution ───────────────────────────
 
 /** Renders an <img> that resolves its src through the MediaProvider when available. */
 function MdImage({ src, alt, title }: { src: string; alt: string; title?: string }) {
-  const resolved = useMediaUrl(src, '.');
+  const safeSrc = sanitizeUrl(src, 'media');
+  const resolved = useMediaUrl(safeSrc ?? '', '.');
+  if (!safeSrc) return null;
   return <img className="squisq-md-image" src={resolved} alt={alt} title={title} />;
 }
 
@@ -408,15 +456,75 @@ function MdImage({ src, alt, title }: { src: string; alt: string; title?: string
 /** True when the htmlElement subtree contains a tag we want to swap
  *  for a React component. Cheap recursive scan — lets us keep the
  *  `dangerouslySetInnerHTML` fast path for everything else. */
+function resolveHtmlNodes(nodes: HtmlNode[], htmlPolicy: HtmlPolicy): HtmlNode[] {
+  if (htmlPolicy === 'strip') return [];
+  if (htmlPolicy === 'trusted') return nodes;
+  return sanitizeHtmlNodes(nodes);
+}
+
 function containsMediaTag(nodes: HtmlNode[]): boolean {
   for (const node of nodes) {
     if (node.type !== 'htmlElement') continue;
-    if (node.tagName === 'video' || node.tagName === 'audio') return true;
+    const tagName = node.tagName.toLowerCase();
+    if (tagName === 'video' || tagName === 'audio') return true;
     if (containsMediaTag(node.children)) return true;
   }
   return false;
 }
 
+/**
+ * Tags that can escape their container and affect the whole host
+ * document — global styling, script execution, external/resource loads,
+ * or framing. Markdown content is frequently untrusted (LLM output,
+ * pasted snippets), and these tags have no business mutating the page
+ * they're embedded in, so they are *always* dropped — even under the
+ * `'trusted'` policy. "Trusted" means "render this HTML's structure
+ * verbatim," not "let it restyle or script the host." A stray `<style>`
+ * applies document-wide (CSS has no per-element scoping outside shadow
+ * DOM / iframes), which is exactly how an embedded game's `<style>`
+ * leaked onto the surrounding app chrome.
+ */
+const DANGEROUS_HTML_TAGS = new Set([
+  'base',
+  'embed',
+  'iframe',
+  'link',
+  'meta',
+  'object',
+  'script',
+  'style',
+  'title',
+]);
+
+/** True when the subtree contains any host-affecting tag (see
+ *  {@link DANGEROUS_HTML_TAGS}). Mirrors {@link containsMediaTag}: keeps
+ *  such content off the verbatim `dangerouslySetInnerHTML` fast path so
+ *  it routes through the React reconstruction, which drops the tag. */
+function containsDangerousTag(nodes: HtmlNode[]): boolean {
+  for (const node of nodes) {
+    if (node.type !== 'htmlElement') continue;
+    if (DANGEROUS_HTML_TAGS.has(node.tagName.toLowerCase())) return true;
+    if (containsDangerousTag(node.children)) return true;
+  }
+  return false;
+}
+
+/**
+ * Raw-string backstop for {@link DANGEROUS_HTML_TAGS}. The structural
+ * {@link containsDangerousTag} check covers the normal case, but a block
+ * parsed with `parseHtml: false` carries an empty `htmlChildren` while
+ * `rawHtml` still holds the markup — so the verbatim fast path scans the
+ * raw string too, guaranteeing a `<style>`/`<script>` can never be
+ * injected into the host document by that path no matter how the node
+ * was produced. The `\b` keeps `<styled-thing>` from matching `<style>`.
+ */
+const DANGEROUS_RAW_HTML_RE =
+  /<\s*\/?\s*(?:base|embed|iframe|link|meta|object|script|style|title)\b/i;
+
+function hasDangerousRawHtml(rawHtml: string): boolean {
+  return DANGEROUS_RAW_HTML_RE.test(rawHtml);
+}
+
 /** A pragmatic shortlist of HTML attributes the raw-HTML walker
  *  passes through to React when reconstructing a non-media element.
  *  Anything outside this list is silently dropped — the media-tag
@@ -432,6 +540,10 @@ const PASSTHROUGH_ATTRS: Record<string, string> = {
   // media-adjacent (used when video/audio appear inside other wrappers)
   width: 'width',
   height: 'height',
+  src: 'src',
+  alt: 'alt',
+  loading: 'loading',
+  decoding: 'decoding',
   // anchor
   href: 'href',
   target: 'target',
@@ -456,7 +568,13 @@ function reactPropsFromAttrs(attrs: Record<string, string>): Record<string, unkn
 }
 
 function renderHtmlElement(el: HtmlElement, key: string): React.ReactNode {
-  if (el.tagName === 'video') {
+  const tagName = el.tagName.toLowerCase();
+  // Final safety net: never reconstruct a host-affecting element (e.g. a
+  // <style> that would leak globally), whatever the policy. The fast path
+  // is gated by containsDangerousTag, so trusted content carrying these
+  // tags lands here — drop the tag and keep the rest of the subtree.
+  if (DANGEROUS_HTML_TAGS.has(tagName)) return null;
+  if (tagName === 'video') {
     return (
       <InlineVideoPlayer
         key={key}
@@ -477,7 +595,7 @@ function renderHtmlElement(el: HtmlElement, key: string): React.ReactNode {
       />
     );
   }
-  if (el.tagName === 'audio') {
+  if (tagName === 'audio') {
     return (
       <InlineAudioPlayer
         key={key}
@@ -494,7 +612,7 @@ function renderHtmlElement(el: HtmlElement, key: string): React.ReactNode {
     );
   }
 
-  const Tag = el.tagName as keyof JSX.IntrinsicElements;
+  const Tag = tagName as keyof JSX.IntrinsicElements;
   const props = reactPropsFromAttrs(el.attributes);
   if (el.selfClosing) {
     return <Tag key={key} {...props} />;
@@ -533,8 +651,14 @@ function renderHtmlNodes(nodes: HtmlNode[], keyPrefix: string): React.ReactNode[
  * <MarkdownRenderer nodes={block.contents} />
  * ```
  */
-export function MarkdownRenderer({ nodes, className }: MarkdownRendererProps) {
+export function MarkdownRenderer({
+  nodes,
+  className,
+  htmlPolicy = 'sanitize',
+}: MarkdownRendererProps) {
   if (!nodes || nodes.length === 0) return null;
 
-  return <div className={`squisq-md ${className || ''}`}>{renderBlocks(nodes)}</div>;
+  return (
+    <div className={`squisq-md ${className || ''}`}>{renderBlocks(nodes, '', htmlPolicy)}</div>
+  );
 }

package/src/MediaClipLayer.tsx

@@ -0,0 +1,135 @@
+/**
+ * MediaClipLayer
+ *
+ * Player-level audio/video elements for the media-clip schedule. Renders one
+ * element per scheduled clip (audio, or document-spanning video) and keeps each
+ * mounted so re-entry doesn't reload; the drive effect seeks/plays only the
+ * clips active at the current time. Multiple concurrent clips (e.g. a
+ * document-spanning narration plus a block clip) are independent elements and
+ * the browser mixes their output.
+ *
+ * Audio clips play unmuted during live playback (silent in render mode, where
+ * frames are captured without sound and audio is muxed offline). Video clips
+ * play muted — their audio, if any, is reproduced by the export mux.
+ */
+
+import { useEffect, useRef } from 'react';
+import type { ScheduledClip } from '@bendyline/squisq/schemas';
+import { useMediaUrl } from './hooks/MediaContext';
+import { useMediaSchedule } from './hooks/useMediaSchedule';
+
+/** Re-seek an element only when it drifts this far from its target (seconds). */
+const DRIFT = 0.25;
+
+export interface MediaClipLayerProps {
+  schedule: ScheduledClip[];
+  currentTime: number;
+  isPlaying: boolean;
+  basePath: string;
+  renderMode?: boolean;
+}
+
+export function MediaClipLayer({
+  schedule,
+  currentTime,
+  isPlaying,
+  basePath,
+  renderMode = false,
+}: MediaClipLayerProps) {
+  const { renderClips, activeIds } = useMediaSchedule(schedule, currentTime);
+  if (renderClips.length === 0) return null;
+  return (
+    <div className="doc-player__media-clips" aria-hidden>
+      {renderClips.map((clip) => (
+        <MediaClipElement
+          key={clip.id}
+          clip={clip}
+          active={activeIds.has(clip.id)}
+          currentTime={currentTime}
+          isPlaying={isPlaying}
+          basePath={basePath}
+          renderMode={renderMode}
+        />
+      ))}
+    </div>
+  );
+}
+
+interface MediaClipElementProps {
+  clip: ScheduledClip;
+  active: boolean;
+  currentTime: number;
+  isPlaying: boolean;
+  basePath: string;
+  renderMode: boolean;
+}
+
+function MediaClipElement({
+  clip,
+  active,
+  currentTime,
+  isPlaying,
+  basePath,
+  renderMode,
+}: MediaClipElementProps) {
+  const ref = useRef<HTMLMediaElement | null>(null);
+  const src = useMediaUrl(clip.src, basePath);
+
+  useEffect(() => {
+    const el = ref.current;
+    if (!el) return;
+    if (!active) {
+      if (!el.paused) el.pause();
+      return;
+    }
+    const target = Math.max(0, clip.sourceIn + (currentTime - clip.absoluteStart));
+    if (renderMode || Math.abs(el.currentTime - target) > DRIFT) {
+      try {
+        el.currentTime = target;
+      } catch {
+        // Seeking before metadata loads throws; the next tick retries.
+      }
+    }
+    if (isPlaying && !renderMode) {
+      const p = el.play();
+      if (p) p.catch(() => {});
+    } else {
+      el.pause();
+    }
+  }, [active, currentTime, isPlaying, renderMode, clip.sourceIn, clip.absoluteStart]);
+
+  const isVideo = clip.kind === 'video';
+  const common = {
+    ref: ref as React.RefObject<never>,
+    src,
+    preload: 'auto' as const,
+    'data-clip-id': clip.id,
+    'data-abs-start': clip.absoluteStart,
+    'data-abs-end': clip.absoluteEnd,
+    'data-source-in': clip.sourceIn,
+  };
+
+  if (isVideo) {
+    // Document-spanning video renders full-bleed behind the blocks.
+    return (
+      <video
+        {...common}
+        muted
+        playsInline
+        style={{
+          position: 'absolute',
+          inset: 0,
+          width: '100%',
+          height: '100%',
+          objectFit: 'cover',
+          zIndex: 0,
+          pointerEvents: 'none',
+        }}
+      />
+    );
+  }
+
+  return (
+    <audio {...common} muted={renderMode} style={{ position: 'absolute', width: 0, height: 0 }} />
+  );
+}

package/src/__tests__/DocPlayer.test.tsx

@@ -0,0 +1,51 @@
+import { describe, it, expect } from 'vitest';
+import { render } from '@testing-library/react';
+import { DocPlayer } from '../DocPlayer';
+import type { Doc } from '@bendyline/squisq/schemas';
+
+function minimalDoc(): Doc {
+  return {
+    articleId: 'smoke',
+    duration: 5,
+    blocks: [{ id: 'b1', startTime: 0, duration: 5, audioSegment: 0, layers: [] }],
+    audio: { segments: [] },
+  };
+}
+
+describe('DocPlayer smoke test', () => {
+  it('renders without crashing in video mode (default)', () => {
+    const { container } = render(<DocPlayer script={minimalDoc()} basePath="/test" />);
+    expect(container.firstChild).toBeTruthy();
+  });
+
+  it('renders without crashing in slideshow mode', () => {
+    const { container } = render(
+      <DocPlayer script={minimalDoc()} basePath="/test" displayMode="slideshow" />,
+    );
+    expect(container.firstChild).toBeTruthy();
+  });
+
+  it('renders without crashing in linear mode', () => {
+    const { container } = render(
+      <DocPlayer script={minimalDoc()} basePath="/test" displayMode="linear" />,
+    );
+    expect(container.firstChild).toBeTruthy();
+  });
+
+  it('exposes playback controls via onControlsReady', () => {
+    let controls: { play: () => void; pause: () => void } | null = null;
+    render(
+      <DocPlayer
+        script={minimalDoc()}
+        basePath="/test"
+        showControls={false}
+        onControlsReady={(c) => {
+          controls = c;
+        }}
+      />,
+    );
+    expect(controls).not.toBeNull();
+    expect(typeof controls!.play).toBe('function');
+    expect(typeof controls!.pause).toBe('function');
+  });
+});