@bendyline/squisq-react 1.4.0 → 1.4.2

package/src/DocPlayerWithSidebar.tsx

@@ -20,19 +20,22 @@
 
 import { useRef, useState, useCallback, useEffect } from 'react';
 import type { Doc } from '@bendyline/squisq/schemas';
-import type { ViewportConfig } from '@bendyline/squisq/schemas';
-import type { AudioProvider } from './hooks/AudioProvider';
+import type { ViewportConfig, Theme } from '@bendyline/squisq/schemas';
+import type { AudioController } from './hooks/AudioController';
 import { DocPlayer } from './DocPlayer';
 import { DocControlsSidebar } from './DocControlsSidebar';
 import type { PlaybackState, PlaybackActions } from './types';
 
 interface DocPlayerWithSidebarProps {
-  script: Doc;
-  basePath: string;
+  /** The Doc to play */
+  doc: Doc;
+  /** Base path for resolving media URLs (default: `'.'`) */
+  basePath?: string;
   autoPlay?: boolean;
   onEnded?: () => void;
   onTimeUpdate?: (time: number) => void;
-  audioProvider?: AudioProvider;
+  /** Optional audio controller (if not provided, uses default HTML5 audio) */
+  audioController?: AudioController;
   muted?: boolean;
   captionsEnabled?: boolean;
   isFullscreen?: boolean;
@@ -41,6 +44,13 @@ interface DocPlayerWithSidebarProps {
   forceViewport?: ViewportConfig;
   /** Called when playing state changes */
   onPlayingChange?: (isPlaying: boolean) => void;
+  /**
+   * Theme for rendering. Forwarded to the inner DocPlayer so the sidebar
+   * (portrait) layout matches the default (landscape) layout — without it the
+   * inner player falls back to DEFAULT_THEME, whose dark text is unreadable
+   * over a hero cover image.
+   */
+  theme?: Theme;
 }
 
 const DEFAULT_STATE: PlaybackState = {
@@ -59,18 +69,19 @@ const DEFAULT_STATE: PlaybackState = {
 };
 
 export function DocPlayerWithSidebar({
-  script,
+  doc,
   basePath,
   autoPlay = false,
   onEnded,
   onTimeUpdate,
-  audioProvider,
+  audioController,
   muted,
   captionsEnabled,
   isFullscreen,
   onFullscreenToggle,
   forceViewport,
   onPlayingChange,
+  theme,
 }: DocPlayerWithSidebarProps) {
   // Store playback state in a ref to avoid triggering re-renders from DocPlayer callbacks
   const stateRef = useRef<PlaybackState>(DEFAULT_STATE);
@@ -114,12 +125,13 @@ export function DocPlayerWithSidebar({
     <div className="doc-player-sidebar-layout">
       <div className="doc-player-sidebar-layout__video">
         <DocPlayer
-          script={script}
+          doc={doc}
+          theme={theme}
           basePath={basePath}
           autoPlay={autoPlay}
           onEnded={onEnded}
           onTimeUpdate={onTimeUpdate}
-          audioProvider={audioProvider}
+          audioController={audioController}
           muted={muted}
           captionsEnabled={captionsEnabled}
           showControls={isFullscreen}

package/src/LinearDocView.tsx

@@ -28,17 +28,32 @@ import {
   type Theme,
 } from '@bendyline/squisq/schemas';
 import { VIEWPORT_PRESETS } from '@bendyline/squisq/schemas';
-import { getLayers, hasTemplate, DEFAULT_THEME, deriveTemplateInputs } from '@bendyline/squisq/doc';
+import {
+  getLayers,
+  hasTemplate,
+  markdownToDoc,
+  DEFAULT_THEME,
+  deriveTemplateInputs,
+} from '@bendyline/squisq/doc';
 import type { RenderContext } from '@bendyline/squisq/doc';
-import { extractPlainText } from '@bendyline/squisq/markdown';
+import { extractPlainText, parseMarkdown } from '@bendyline/squisq/markdown';
 import { BlockRenderer } from './BlockRenderer';
 import { MarkdownRenderer } from './MarkdownRenderer';
 
 // ── Props ──────────────────────────────────────────────────────────
 
 export interface LinearDocViewProps {
-  /** The Doc to render */
-  doc: Doc;
+  /**
+   * The Doc to render. Wins over `markdown` when both are provided.
+   * When neither `doc` nor `markdown` is given, an empty container renders.
+   */
+  doc?: Doc;
+  /**
+   * Markdown source to render. When `doc` is absent, the markdown is parsed
+   * and converted to a Doc via `markdownToDoc(parseMarkdown(markdown))`.
+   * Ignored when `doc` is provided.
+   */
+  markdown?: string;
   /** Base path for resolving media URLs (images, etc.) */
   basePath?: string;
   /** Viewport config for SVG card rendering (default: landscape) */
@@ -78,16 +93,33 @@ export type ImageDisplayMode = 'inline' | 'thumbnail';
 
 // ── Helpers ────────────────────────────────────────────────────────
 
+// Unknown template names we've already warned about (module-level so each
+// name warns at most once per page, not once per render).
+const warnedUnknownTemplates = new Set<string>();
+
 /**
  * Determine whether a block has a template annotation that should be
  * rendered as a visual SVG card. A block is "annotated" when:
  * 1. Its sourceHeading has a templateAnnotation, AND
  * 2. The annotated template exists in the registry
+ *
+ * Blocks annotated with a template that is NOT in the registry fall back
+ * to plain markdown rendering, with a one-shot dev-visible warning per
+ * unknown template name.
  */
 function isAnnotatedBlock(block: Block): boolean {
   const annotation = block.sourceHeading?.templateAnnotation;
-  if (!annotation) return false;
-  return !!annotation.template && hasTemplate(annotation.template);
+  if (!annotation?.template) return false;
+  if (!hasTemplate(annotation.template)) {
+    if (!warnedUnknownTemplates.has(annotation.template)) {
+      warnedUnknownTemplates.add(annotation.template);
+      console.warn(
+        `[squisq] Unknown template "${annotation.template}" — rendering the block as plain markdown.`,
+      );
+    }
+    return false;
+  }
+  return true;
 }
 
 /**
@@ -221,8 +253,6 @@ function BlockSection({ block, basePath, viewport, renderContext, blockIndex }:
   );
 }
 
-// ── Template Defaults (mirrored from PreviewPanel) ─────────────────
-
 // ── Main Component ─────────────────────────────────────────────────
 
 /**
@@ -239,6 +269,7 @@ function BlockSection({ block, basePath, viewport, renderContext, blockIndex }:
  */
 export function LinearDocView({
   doc,
+  markdown,
   basePath = '/',
   viewport,
   className,
@@ -248,7 +279,18 @@ export function LinearDocView({
   imageDisplayMode = 'inline',
 }: LinearDocViewProps) {
   const activeViewport = viewport ?? VIEWPORT_PRESETS.landscape;
-  const totalBlocks = useMemo(() => countAll(doc.blocks), [doc.blocks]);
+
+  // Parse markdown into a Doc only when no explicit doc is supplied.
+  const markdownDoc = useMemo(
+    () => (!doc && markdown !== undefined ? markdownToDoc(parseMarkdown(markdown)) : undefined),
+    [doc, markdown],
+  );
+  const resolvedDoc = doc ?? markdownDoc;
+
+  const totalBlocks = useMemo(
+    () => (resolvedDoc ? countAll(resolvedDoc.blocks) : 0),
+    [resolvedDoc],
+  );
   const autoSurface = useAutoSurface(surface === 'auto');
   const resolvedSurface: SurfaceScheme | undefined = surface === 'auto' ? autoSurface : surface;
 
@@ -266,6 +308,13 @@ export function LinearDocView({
   }, [activeViewport, totalBlocks, theme, resolvedSurface]);
 
   const activeTheme = renderContext.theme!;
+
+  // Nothing to render — keep an empty (but classed) container so hosts can
+  // still target/measure the view.
+  if (!resolvedDoc) {
+    return <div className={`squisq-linear squisq-linear--empty ${className || ''}`} />;
+  }
+
   const bgColor = activeTheme.colors.background;
   const textColor = activeTheme.colors.text;
   const mutedColor = activeTheme.colors.textMuted;
@@ -428,7 +477,7 @@ export function LinearDocView({
             background: color-mix(in srgb, var(--squisq-linear-primary) 8%, transparent);
           }
         `}</style>
-        {doc.blocks.map((block, i) => (
+        {resolvedDoc.blocks.map((block, i) => (
           <BlockSection
             key={block.id}
             block={block}

package/src/MarkdownRenderer.tsx

@@ -43,15 +43,29 @@ export interface MarkdownRendererProps {
    * event handlers, and executable URL schemes before rendering.
    */
   htmlPolicy?: HtmlPolicy;
+  /**
+   * Extra URL schemes to allow on links (e.g. a host app's internal
+   * navigation scheme it intercepts on click). Executable schemes are
+   * never allowed regardless. See {@link SanitizeUrlOptions}.
+   */
+  linkSchemes?: readonly string[];
 }
 
+/** Options threaded through the recursive renderers. */
+interface RenderCtx {
+  htmlPolicy: HtmlPolicy;
+  linkSchemes?: readonly string[];
+}
+
+const DEFAULT_CTX: RenderCtx = { htmlPolicy: 'sanitize' };
+
 // ── Inline Renderer ────────────────────────────────────────────────
 
 /** Render an array of inline nodes into React elements. */
 function renderInline(
   nodes: MarkdownInlineNode[],
   keyPrefix = '',
-  htmlPolicy: HtmlPolicy = 'sanitize',
+  ctx: RenderCtx = DEFAULT_CTX,
 ): React.ReactNode[] {
   return nodes.map((node, i) => {
     const key = `${keyPrefix}i${i}`;
@@ -79,21 +93,21 @@ function renderInline(
       case 'emphasis':
         return (
           <em key={key} className="squisq-md-em">
-            {renderInline(node.children, key, htmlPolicy)}
+            {renderInline(node.children, key, ctx)}
           </em>
         );
 
       case 'strong':
         return (
           <strong key={key} className="squisq-md-strong">
-            {renderInline(node.children, key, htmlPolicy)}
+            {renderInline(node.children, key, ctx)}
           </strong>
         );
 
       case 'delete':
         return (
           <del key={key} className="squisq-md-del">
-            {renderInline(node.children, key, htmlPolicy)}
+            {renderInline(node.children, key, ctx)}
           </del>
         );
 
@@ -105,11 +119,11 @@ function renderInline(
         );
 
       case 'link': {
-        const href = sanitizeUrl(node.url, 'link');
+        const href = sanitizeUrl(node.url, 'link', { extraLinkSchemes: ctx.linkSchemes });
         if (!href) {
           return (
             <span key={key} className="squisq-md-link squisq-md-link--blocked">
-              {renderInline(node.children, key, htmlPolicy)}
+              {renderInline(node.children, key, ctx)}
             </span>
           );
         }
@@ -122,7 +136,7 @@ function renderInline(
             target="_blank"
             rel="noopener noreferrer"
           >
-            {renderInline(node.children, key, htmlPolicy)}
+            {renderInline(node.children, key, ctx)}
           </a>
         );
       }
@@ -143,11 +157,11 @@ function renderInline(
         );
 
       case 'htmlInline':
-        if (htmlPolicy === 'strip') return null;
+        if (ctx.htmlPolicy === 'strip') return null;
         // Fast path: no <video>/<audio> in the subtree → use the original
         // rawHtml passthrough (preserves arbitrary HTML for custom embeds).
         if (
-          htmlPolicy === 'trusted' &&
+          ctx.htmlPolicy === 'trusted' &&
           !containsMediaTag(node.htmlChildren) &&
           !containsDangerousTag(node.htmlChildren) &&
           !hasDangerousRawHtml(node.rawHtml)
@@ -164,7 +178,7 @@ function renderInline(
         // go through MediaContext-aware player components.
         return (
           <span key={key} className="squisq-md-html-inline">
-            {renderHtmlNodes(resolveHtmlNodes(node.htmlChildren, htmlPolicy), `${key}h`)}
+            {renderHtmlNodes(resolveHtmlNodes(node.htmlChildren, ctx.htmlPolicy), `${key}h`)}
           </span>
         );
 
@@ -179,7 +193,7 @@ function renderInline(
         // Render as plain text (definition targets not available at render time)
         return (
           <span key={key} className="squisq-md-link-ref">
-            {renderInline(node.children, key, htmlPolicy)}
+            {renderInline(node.children, key, ctx)}
           </span>
         );
 
@@ -193,7 +207,7 @@ function renderInline(
       case 'textDirective':
         return (
           <span key={key} className="squisq-md-text-directive" data-directive={node.name}>
-            {renderInline(node.children, key, htmlPolicy)}
+            {renderInline(node.children, key, ctx)}
           </span>
         );
 
@@ -223,13 +237,13 @@ function renderInline(
 function renderBlock(
   node: MarkdownBlockNode,
   key: string,
-  htmlPolicy: HtmlPolicy = 'sanitize',
+  ctx: RenderCtx = DEFAULT_CTX,
 ): React.ReactNode {
   switch (node.type) {
     case 'paragraph':
       return (
         <p key={key} className="squisq-md-p">
-          {renderInline(node.children, key, htmlPolicy)}
+          {renderInline(node.children, key, ctx)}
         </p>
       );
 
@@ -237,7 +251,7 @@ function renderBlock(
       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, htmlPolicy)}
+          {renderInline(node.children, key, ctx)}
         </Tag>
       );
     }
@@ -245,7 +259,7 @@ function renderBlock(
     case 'blockquote':
       return (
         <blockquote key={key} className="squisq-md-blockquote">
-          {renderBlocks(node.children, key, htmlPolicy)}
+          {renderBlocks(node.children, key, ctx)}
         </blockquote>
       );
 
@@ -253,13 +267,13 @@ function renderBlock(
       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}`, htmlPolicy))}
+            {node.children.map((item, i) => renderListItem(item, `${key}li${i}`, ctx))}
           </ol>
         );
       }
       return (
         <ul key={key} className="squisq-md-list squisq-md-ul">
-          {node.children.map((item, i) => renderListItem(item, `${key}li${i}`, htmlPolicy))}
+          {node.children.map((item, i) => renderListItem(item, `${key}li${i}`, ctx))}
         </ul>
       );
 
@@ -274,14 +288,14 @@ function renderBlock(
       return <hr key={key} className="squisq-md-hr" />;
 
     case 'table':
-      return renderTable(node.children, node.align, key, htmlPolicy);
+      return renderTable(node.children, node.align, key, ctx);
 
     case 'htmlBlock':
-      if (htmlPolicy === 'strip') return null;
+      if (ctx.htmlPolicy === 'strip') return null;
       // Fast path: no <video>/<audio> → preserve the existing rawHtml
       // passthrough so arbitrary HTML embeds still survive verbatim.
       if (
-        htmlPolicy === 'trusted' &&
+        ctx.htmlPolicy === 'trusted' &&
         !containsMediaTag(node.htmlChildren) &&
         !containsDangerousTag(node.htmlChildren) &&
         !hasDangerousRawHtml(node.rawHtml)
@@ -298,7 +312,7 @@ function renderBlock(
       // route through the player components and resolve via MediaContext.
       return (
         <div key={key} className="squisq-md-html-block">
-          {renderHtmlNodes(resolveHtmlNodes(node.htmlChildren, htmlPolicy), `${key}h`)}
+          {renderHtmlNodes(resolveHtmlNodes(node.htmlChildren, ctx.htmlPolicy), `${key}h`)}
         </div>
       );
 
@@ -317,7 +331,7 @@ function renderBlock(
       return (
         <div key={key} className="squisq-md-footnote-def" id={`fn-${node.identifier}`}>
           <sup>{node.label ?? node.identifier}</sup>
-          {renderBlocks(node.children, key, htmlPolicy)}
+          {renderBlocks(node.children, key, ctx)}
         </div>
       );
 
@@ -329,7 +343,7 @@ function renderBlock(
           data-directive={node.name}
         >
           {node.label && <div className="squisq-md-directive-label">{node.label}</div>}
-          {renderBlocks(node.children, key, htmlPolicy)}
+          {renderBlocks(node.children, key, ctx)}
         </div>
       );
 
@@ -340,7 +354,7 @@ function renderBlock(
           className={`squisq-md-directive squisq-md-directive-${node.name}`}
           data-directive={node.name}
         >
-          {renderInline(node.children, key, htmlPolicy)}
+          {renderInline(node.children, key, ctx)}
         </div>
       );
 
@@ -351,13 +365,13 @@ function renderBlock(
             if (child.type === 'definitionTerm') {
               return (
                 <dt key={`${key}dt${i}`} className="squisq-md-dt">
-                  {renderInline(child.children, `${key}dt${i}`, htmlPolicy)}
+                  {renderInline(child.children, `${key}dt${i}`, ctx)}
                 </dt>
               );
             }
             return (
               <dd key={`${key}dd${i}`} className="squisq-md-dd">
-                {renderBlocks(child.children, `${key}dd${i}`, htmlPolicy)}
+                {renderBlocks(child.children, `${key}dd${i}`, ctx)}
               </dd>
             );
           })}
@@ -373,7 +387,7 @@ function renderBlock(
 function renderListItem(
   item: MarkdownListItem,
   key: string,
-  htmlPolicy: HtmlPolicy = 'sanitize',
+  ctx: RenderCtx = DEFAULT_CTX,
 ): React.ReactNode {
   const isTask = item.checked !== null && item.checked !== undefined;
   return (
@@ -381,7 +395,7 @@ function renderListItem(
       {isTask && (
         <input type="checkbox" checked={!!item.checked} readOnly className="squisq-md-checkbox" />
       )}
-      {renderBlocks(item.children, key, htmlPolicy)}
+      {renderBlocks(item.children, key, ctx)}
     </li>
   );
 }
@@ -391,7 +405,7 @@ function renderTable(
   rows: MarkdownTableRow[],
   align: (('left' | 'right' | 'center') | null)[] | undefined,
   key: string,
-  htmlPolicy: HtmlPolicy = 'sanitize',
+  ctx: RenderCtx = DEFAULT_CTX,
 ): React.ReactNode {
   const [headerRow, ...bodyRows] = rows;
   return (
@@ -405,7 +419,7 @@ function renderTable(
                 className="squisq-md-th"
                 style={align?.[ci] ? { textAlign: align[ci]! } : undefined}
               >
-                {renderInline(cell.children, `${key}th${ci}`, htmlPolicy)}
+                {renderInline(cell.children, `${key}th${ci}`, ctx)}
               </th>
             ))}
           </tr>
@@ -421,7 +435,7 @@ function renderTable(
                   className="squisq-md-td"
                   style={align?.[ci] ? { textAlign: align[ci]! } : undefined}
                 >
-                  {renderInline(cell.children, `${key}td${ri}-${ci}`, htmlPolicy)}
+                  {renderInline(cell.children, `${key}td${ri}-${ci}`, ctx)}
                 </td>
               ))}
             </tr>
@@ -436,9 +450,9 @@ function renderTable(
 function renderBlocks(
   nodes: MarkdownBlockNode[],
   keyPrefix = '',
-  htmlPolicy: HtmlPolicy = 'sanitize',
+  ctx: RenderCtx = DEFAULT_CTX,
 ): React.ReactNode[] {
-  return nodes.map((node, i) => renderBlock(node, `${keyPrefix}b${i}`, htmlPolicy));
+  return nodes.map((node, i) => renderBlock(node, `${keyPrefix}b${i}`, ctx));
 }
 
 // ── Image with MediaProvider resolution ───────────────────────────
@@ -655,10 +669,13 @@ export function MarkdownRenderer({
   nodes,
   className,
   htmlPolicy = 'sanitize',
+  linkSchemes,
 }: MarkdownRendererProps) {
   if (!nodes || nodes.length === 0) return null;
 
   return (
-    <div className={`squisq-md ${className || ''}`}>{renderBlocks(nodes, '', htmlPolicy)}</div>
+    <div className={`squisq-md ${className || ''}`}>
+      {renderBlocks(nodes, '', { htmlPolicy, linkSchemes })}
+    </div>
   );
 }

package/src/__tests__/DocPlayer.test.tsx

@@ -1,5 +1,5 @@
-import { describe, it, expect } from 'vitest';
-import { render } from '@testing-library/react';
+import { afterAll, beforeAll, describe, expect, it, vi } from 'vitest';
+import { fireEvent, render, screen, waitFor } from '@testing-library/react';
 import { DocPlayer } from '../DocPlayer';
 import type { Doc } from '@bendyline/squisq/schemas';
 
@@ -12,22 +12,71 @@ function minimalDoc(): Doc {
   };
 }
 
+function docWithCover(): Doc {
+  return {
+    ...minimalDoc(),
+    startBlock: {
+      title: 'Managed Cover',
+      subtitle: 'Generated by Squisq',
+    },
+  };
+}
+
 describe('DocPlayer smoke test', () => {
+  beforeAll(() => {
+    vi.spyOn(window.HTMLMediaElement.prototype, 'pause').mockImplementation(() => {});
+  });
+
+  afterAll(() => {
+    vi.restoreAllMocks();
+  });
+
   it('renders without crashing in video mode (default)', () => {
-    const { container } = render(<DocPlayer script={minimalDoc()} basePath="/test" />);
+    const { container } = render(<DocPlayer doc={minimalDoc()} basePath="/test" />);
     expect(container.firstChild).toBeTruthy();
   });
 
   it('renders without crashing in slideshow mode', () => {
     const { container } = render(
-      <DocPlayer script={minimalDoc()} basePath="/test" displayMode="slideshow" />,
+      <DocPlayer doc={minimalDoc()} basePath="/test" displayMode="slideshow" />,
     );
     expect(container.firstChild).toBeTruthy();
   });
 
+  it('shows the managed cover as the first slideshow entry by default', async () => {
+    const { container } = render(
+      <DocPlayer doc={docWithCover()} basePath="/test" displayMode="slideshow" />,
+    );
+    await waitFor(() => expect(container.textContent).toContain('Managed Cover'));
+    expect(screen.getByTestId('slide-counter').textContent).toBe('Cover');
+  });
+
+  it('can suppress the managed cover slide', () => {
+    const { container } = render(
+      <DocPlayer
+        doc={docWithCover()}
+        basePath="/test"
+        displayMode="slideshow"
+        showCoverSlide={false}
+      />,
+    );
+    expect(container.textContent).not.toContain('Managed Cover');
+    expect(screen.getByTestId('slide-counter').textContent).toBe('1 / 1');
+  });
+
+  it('advances from slideshow cover to slide 1', async () => {
+    const { container } = render(
+      <DocPlayer doc={docWithCover()} basePath="/test" displayMode="slideshow" />,
+    );
+    await waitFor(() => expect(screen.getByTestId('slide-counter').textContent).toBe('Cover'));
+    fireEvent.click(screen.getByTestId('slide-next'));
+    await waitFor(() => expect(screen.getByTestId('slide-counter').textContent).toBe('1 / 1'));
+    expect(container.textContent).not.toContain('Managed Cover');
+  });
+
   it('renders without crashing in linear mode', () => {
     const { container } = render(
-      <DocPlayer script={minimalDoc()} basePath="/test" displayMode="linear" />,
+      <DocPlayer doc={minimalDoc()} basePath="/test" displayMode="linear" />,
     );
     expect(container.firstChild).toBeTruthy();
   });
@@ -36,7 +85,7 @@ describe('DocPlayer smoke test', () => {
     let controls: { play: () => void; pause: () => void } | null = null;
     render(
       <DocPlayer
-        script={minimalDoc()}
+        doc={minimalDoc()}
         basePath="/test"
         showControls={false}
         onControlsReady={(c) => {
@@ -49,3 +98,33 @@ describe('DocPlayer smoke test', () => {
     expect(typeof controls!.pause).toBe('function');
   });
 });
+
+describe('DocPlayer front door (doc / markdown resolution)', () => {
+  it('renders a doc built from the markdown prop', () => {
+    const { container } = render(
+      <DocPlayer markdown={'# Hello From Markdown\n\nBody text here.'} displayMode="linear" />,
+    );
+    expect(container.querySelector('.doc-player')).toBeTruthy();
+    expect(container.textContent).toContain('Hello From Markdown');
+  });
+
+  it('doc wins over markdown when both are provided', () => {
+    const { container } = render(
+      <DocPlayer doc={minimalDoc()} markdown="# Markdown Loses" displayMode="linear" />,
+    );
+    expect(container.querySelector('.doc-player')).toBeTruthy();
+    expect(container.textContent).not.toContain('Markdown Loses');
+  });
+
+  it('renders an empty state without throwing when neither doc nor markdown is given', () => {
+    const { container } = render(<DocPlayer />);
+    const empty = container.querySelector('.doc-player--empty');
+    expect(empty).toBeTruthy();
+    expect(empty!.classList.contains('doc-player')).toBe(true);
+  });
+
+  it('defaults basePath when omitted', () => {
+    const { container } = render(<DocPlayer doc={minimalDoc()} />);
+    expect(container.querySelector('.doc-player')).toBeTruthy();
+  });
+});

package/src/__tests__/DocPlayerStylesSentinel.test.tsx

@@ -0,0 +1,41 @@
+/**
+ * Missing-stylesheet sentinel test.
+ *
+ * Lives in its own file so it owns a fresh module instance of DocPlayer
+ * (vitest isolates module registries per test file) — the sentinel warning
+ * is one-shot at module level, so this file's first mount deterministically
+ * observes it.
+ */
+
+import { describe, it, expect, vi, afterEach } from 'vitest';
+import { render } from '@testing-library/react';
+import { DocPlayer } from '../DocPlayer';
+import type { Doc } from '@bendyline/squisq/schemas';
+
+function minimalDoc(): Doc {
+  return {
+    articleId: 'sentinel',
+    duration: 5,
+    blocks: [{ id: 'b1', startTime: 0, duration: 5, audioSegment: 0, layers: [] }],
+    audio: { segments: [] },
+  };
+}
+
+afterEach(() => {
+  vi.restoreAllMocks();
+});
+
+describe('DocPlayer missing-CSS sentinel', () => {
+  it('warns once (and only once) in dev when the stylesheet is not loaded', () => {
+    const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
+
+    render(<DocPlayer doc={minimalDoc()} />);
+    const sentinelCalls = () =>
+      warnSpy.mock.calls.filter((c) => String(c[0]).includes('squisq-react/styles'));
+    expect(sentinelCalls().length).toBe(1);
+
+    // Second mount must not warn again — module-level one-shot.
+    render(<DocPlayer doc={minimalDoc()} />);
+    expect(sentinelCalls().length).toBe(1);
+  });
+});