@bendyline/squisq-react 1.3.2 → 1.4.1

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/DocProgressBar.tsx

@@ -41,6 +41,15 @@ export function DocProgressBar({
   const progressBarRef = useRef<HTMLDivElement>(null);
   const [hoverPosition, setHoverPosition] = useState<number | null>(null);
 
+  // Fill position tracks the same timeline as the clock readout and the block
+  // marker dots — elapsed playback time over the audio `totalDuration`. (We
+  // deliberately don't use `state.docProgress`, which is keyed to the doc's
+  // estimated `script.duration`; when that diverges from the actual playback
+  // length — e.g. the editor preview's reading-time estimate — the fill would
+  // desync from the clock and the dots.)
+  const playProgress =
+    state.totalDuration > 0 ? Math.max(0, Math.min(1, state.currentTime / state.totalDuration)) : 0;
+
   const handleProgressHover = useCallback((e: React.MouseEvent) => {
     const bar = progressBarRef.current;
     if (!bar) return;
@@ -99,16 +108,25 @@ export function DocProgressBar({
         }}
       />
 
-      {/* Progress fill */}
+      {/* Progress fill.
+          No CSS `width` transition: the fill is driven by frequent JS updates
+          (the synthetic fallback timer runs ~60fps; real audio fires
+          `timeupdate` several times/sec), so it's already smooth. A CSS
+          transition here actively breaks playback — after a discontinuous
+          backward seek, the per-frame inline-width updates on resume keep
+          interrupting the in-flight transition before it advances, so the
+          *rendered* width latches at the seek position even though the inline
+          style (and the clock) keep climbing. The result is a frozen-looking
+          bar while time advances. Update width instantly instead. */}
       <div
+        data-testid="doc-progress-fill"
         style={{
           position: 'absolute',
           left: 0,
-          width: `${state.docProgress * 100}%`,
+          width: `${playProgress * 100}%`,
           height: '6px',
           background: '#5b9bd5',
           borderRadius: '3px',
-          transition: 'width 0.1s',
         }}
       />
 

package/src/LinearDocView.tsx

@@ -28,18 +28,32 @@ import {
   type Theme,
 } from '@bendyline/squisq/schemas';
 import { VIEWPORT_PRESETS } from '@bendyline/squisq/schemas';
-import { getLayers, hasTemplate, DEFAULT_THEME } 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 type { MarkdownBlockNode, MarkdownList, MarkdownTable } 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) */
@@ -79,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;
 }
 
 /**
@@ -126,7 +157,6 @@ function BlockSection({ block, basePath, viewport, renderContext, blockIndex }:
 
     const annotation = block.sourceHeading!.templateAnnotation!;
     const headingText = extractPlainText(block.sourceHeading!);
-    const bodyText = extractBodyPlainText(block.contents);
 
     // Build a TemplateBlock-compatible object
     const templateBlock: Record<string, unknown> = {
@@ -136,12 +166,14 @@ function BlockSection({ block, basePath, viewport, renderContext, blockIndex }:
       duration: 1,
       audioSegment: 0,
       title: headingText,
-      ...getTemplateDefaults(
+      ...(deriveTemplateInputs(
         annotation.template ?? 'sectionHeader',
         headingText,
-        bodyText,
         block.contents,
-      ),
+        {
+          placeholders: true,
+        },
+      ) ?? {}),
       ...annotation.params,
       ...block.templateOverrides,
     };
@@ -221,198 +253,6 @@ function BlockSection({ block, basePath, viewport, renderContext, blockIndex }:
   );
 }
 
-// ── Template Defaults (mirrored from PreviewPanel) ─────────────────
-
-/** Extract plain text from block contents. */
-function extractBodyPlainText(contents?: MarkdownBlockNode[]): string {
-  if (!contents || contents.length === 0) return '';
-  return contents
-    .map((n) => extractPlainText(n))
-    .join('\n')
-    .trim();
-}
-
-/** Extract list items as plain text. */
-function extractListItems(contents?: MarkdownBlockNode[]): string[] {
-  if (!contents) return [];
-  const items: string[] = [];
-  for (const node of contents) {
-    if (node.type === 'list') {
-      for (const item of (node as MarkdownList).children) {
-        const text = extractPlainText(item).trim();
-        if (text) items.push(text);
-      }
-    }
-  }
-  return items;
-}
-
-/** First image discovered in a block's body, with any explicit
- *  dimensions captured (set by `<img width>` / `<img height>` in raw
- *  HTML — markdown shorthand has no syntax for dimensions). */
-interface FirstImage {
-  src: string;
-  alt: string;
-  width?: number;
-  height?: number;
-}
-
-/**
- * Find the first image referenced anywhere in block contents — both
- * markdown shorthand `![alt](url)` (type `image`) and raw HTML `<img>`
- * tags (type `htmlBlock`/`htmlInline`). The WYSIWYG editor emits the
- * HTML form whenever a user resizes an image (markdown shorthand has no
- * width syntax), so missing that path silently breaks every resized
- * image in the linear view.
- */
-function extractFirstImage(contents: MarkdownBlockNode[] | undefined): FirstImage | null {
-  if (!contents || contents.length === 0) return null;
-
-  function fromHtml(nodes: unknown[]): FirstImage | null {
-    for (const node of nodes) {
-      if (!node || typeof node !== 'object') continue;
-      const n = node as Record<string, unknown>;
-      if (n.type === 'htmlElement' && n.tagName === 'img') {
-        const attrs = n.attributes as Record<string, string> | undefined;
-        if (attrs && typeof attrs.src === 'string' && attrs.src) {
-          return {
-            src: attrs.src,
-            alt: typeof attrs.alt === 'string' ? attrs.alt : '',
-            width: parseDim(attrs.width),
-            height: parseDim(attrs.height),
-          };
-        }
-      }
-      if (Array.isArray(n.children)) {
-        const found = fromHtml(n.children);
-        if (found) return found;
-      }
-    }
-    return null;
-  }
-
-  function walk(node: unknown): FirstImage | null {
-    if (!node || typeof node !== 'object') return null;
-    const n = node as Record<string, unknown>;
-    if (n.type === 'image' && typeof n.url === 'string' && n.url) {
-      return { src: n.url, alt: typeof n.alt === 'string' ? n.alt : '' };
-    }
-    if ((n.type === 'htmlBlock' || n.type === 'htmlInline') && Array.isArray(n.htmlChildren)) {
-      const found = fromHtml(n.htmlChildren);
-      if (found) return found;
-    }
-    if (Array.isArray(n.children)) {
-      for (const child of n.children) {
-        const found = walk(child);
-        if (found) return found;
-      }
-    }
-    return null;
-  }
-
-  for (const node of contents) {
-    const found = walk(node);
-    if (found) return found;
-  }
-  return null;
-}
-
-/** Parse a `width`/`height` HTML attribute to a positive number. */
-function parseDim(raw: string | undefined): number | undefined {
-  if (raw === undefined) return undefined;
-  const n = parseFloat(raw);
-  return Number.isFinite(n) && n > 0 ? n : undefined;
-}
-
-/** Extract table data (headers, rows, alignment) from block contents. */
-function extractTableData(contents?: MarkdownBlockNode[]): {
-  headers: string[];
-  rows: string[][];
-  align?: (('left' | 'right' | 'center') | null)[];
-} | null {
-  if (!contents) return null;
-  for (const node of contents) {
-    if (node.type === 'table') {
-      const table = node as MarkdownTable;
-      const [headerRow, ...bodyRows] = table.children;
-      if (!headerRow) return null;
-      const headers = headerRow.children.map((cell) => extractPlainText(cell).trim());
-      const rows = bodyRows.map((row) => row.children.map((cell) => extractPlainText(cell).trim()));
-      return { headers, rows, align: table.align };
-    }
-  }
-  return null;
-}
-
-/**
- * Provide sensible default fields for templates that require more than
- * just a `title`. Prevents crashes from undefined required fields.
- */
-function getTemplateDefaults(
-  templateName: string,
-  headingText: string,
-  bodyText: string,
-  contents?: MarkdownBlockNode[],
-): Record<string, unknown> {
-  switch (templateName) {
-    case 'statHighlight':
-      return { stat: headingText, description: bodyText || headingText };
-    case 'quote':
-    case 'fullBleedQuote':
-    case 'pullQuote':
-      return { quote: bodyText || headingText };
-    case 'factCard':
-      return { fact: headingText, explanation: bodyText || headingText };
-    case 'comparisonBar':
-      return { leftLabel: 'A', leftValue: 60, rightLabel: 'B', rightValue: 40 };
-    case 'list': {
-      const items = extractListItems(contents);
-      return { items: items.length > 0 ? items : ['Item 1', 'Item 2', 'Item 3'] };
-    }
-    case 'definitionCard':
-      return { term: headingText, definition: bodyText || headingText };
-    case 'dateEvent':
-      return { date: headingText, description: bodyText || headingText };
-    case 'dataTable': {
-      const tableData = extractTableData(contents);
-      return tableData ?? { headers: ['Column'], rows: [['Data']] };
-    }
-    case 'imageWithCaption': {
-      // The template requires `imageSrc` — without it the image layer
-      // renders a broken `<img src=undefined>`. Pull the first image
-      // out of the block's body (markdown shorthand or HTML <img>) and
-      // use the heading as a caption fallback so a bare `# Title
-      // [Image with Caption]` block renders something sensible.
-      const img = extractFirstImage(contents);
-      if (!img) return { caption: headingText };
-      return {
-        imageSrc: img.src,
-        imageAlt: img.alt || headingText,
-        caption: headingText,
-      };
-    }
-    case 'leftFeature':
-    case 'rightFeature': {
-      // Feature blocks pair an image with the heading + the first
-      // paragraph of body text. Both inputs come from the section's
-      // contents — the image via the same scan used by imageWithCaption,
-      // the body text via the plain-text extractor that's already in
-      // scope here.
-      const img = extractFirstImage(contents);
-      return {
-        imageSrc: img?.src ?? '',
-        imageAlt: img?.alt || headingText,
-        imageWidth: img?.width,
-        imageHeight: img?.height,
-        title: headingText,
-        body: bodyText,
-      };
-    }
-    default:
-      return {};
-  }
-}
-
 // ── Main Component ─────────────────────────────────────────────────
 
 /**
@@ -429,6 +269,7 @@ function getTemplateDefaults(
  */
 export function LinearDocView({
   doc,
+  markdown,
   basePath = '/',
   viewport,
   className,
@@ -438,20 +279,42 @@ 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;
 
   const renderContext: RenderContext = useMemo(() => {
     const baseTheme = theme ?? DEFAULT_THEME;
+    const effectiveTheme = resolvedSurface ? applySurface(baseTheme, resolvedSurface) : baseTheme;
     return {
-      theme: resolvedSurface ? applySurface(baseTheme, resolvedSurface) : baseTheme,
+      theme: effectiveTheme,
       viewport: activeViewport,
       totalBlocks,
+      // Theme atmosphere (vignette/grain/gradient persistent layers) shows
+      // on the inline template cards so they match the player's look.
+      persistentLayers: effectiveTheme.persistentLayers,
     };
   }, [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;
@@ -614,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}