@bendyline/squisq-react 0.1.2

package/src/hooks/useViewportOrientation.ts

@@ -0,0 +1,117 @@
+/**
+ * useViewportOrientation Hook
+ *
+ * Detects the current viewport orientation and returns the appropriate
+ * VIEWPORT_PRESET for rendering docs. Automatically updates when
+ * the window is resized.
+ *
+ * Thresholds:
+ * - Portrait: height > width * 1.2 (significantly taller than wide)
+ * - Square: width and height within 20% of each other
+ * - Landscape: width > height * 1.2 (significantly wider than tall)
+ */
+
+import { useState, useEffect, useMemo } from 'react';
+import {
+  VIEWPORT_PRESETS,
+  type ViewportConfig,
+  type ViewportOrientation,
+} from '@bendyline/squisq/doc';
+
+interface UseViewportOrientationResult {
+  /** Current viewport preset configuration */
+  viewport: ViewportConfig;
+  /** Current orientation name */
+  orientation: ViewportOrientation;
+  /** Current window dimensions */
+  windowSize: { width: number; height: number };
+}
+
+/**
+ * Determine viewport orientation from window dimensions.
+ */
+function getOrientationFromWindow(width: number, height: number): ViewportOrientation {
+  const ratio = width / height;
+
+  // Use thresholds to determine orientation
+  // - Ratio > 1.2 = landscape (wider than tall)
+  // - Ratio < 0.83 (1/1.2) = portrait (taller than wide)
+  // - Otherwise = square-ish, use landscape for better readability
+  if (ratio > 1.2) {
+    return 'landscape';
+  } else if (ratio < 0.83) {
+    return 'portrait';
+  } else {
+    // Near-square viewports: use landscape for better text readability
+    // Could also use 'square' preset if available and desired
+    return 'landscape';
+  }
+}
+
+/**
+ * Get the appropriate viewport preset for an orientation.
+ */
+function getViewportForOrientation(orientation: ViewportOrientation): ViewportConfig {
+  switch (orientation) {
+    case 'portrait':
+      return VIEWPORT_PRESETS.portrait;
+    case 'square':
+      return VIEWPORT_PRESETS.square;
+    case 'landscape':
+    default:
+      return VIEWPORT_PRESETS.landscape;
+  }
+}
+
+/**
+ * Hook to detect viewport orientation and return appropriate preset.
+ * Updates automatically when window is resized.
+ */
+export function useViewportOrientation(): UseViewportOrientationResult {
+  const [windowSize, setWindowSize] = useState(() => ({
+    width: typeof window !== 'undefined' ? window.innerWidth : 1920,
+    height: typeof window !== 'undefined' ? window.innerHeight : 1080,
+  }));
+
+  // Listen for window resize
+  useEffect(() => {
+    if (typeof window === 'undefined') return;
+
+    const handleResize = () => {
+      setWindowSize({
+        width: window.innerWidth,
+        height: window.innerHeight,
+      });
+    };
+
+    // Debounce resize handler to avoid excessive re-renders
+    let timeoutId: ReturnType<typeof setTimeout>;
+    const debouncedResize = () => {
+      clearTimeout(timeoutId);
+      timeoutId = setTimeout(handleResize, 100);
+    };
+
+    window.addEventListener('resize', debouncedResize);
+    return () => {
+      window.removeEventListener('resize', debouncedResize);
+      clearTimeout(timeoutId);
+    };
+  }, []);
+
+  // Calculate orientation from window size
+  const orientation = useMemo(
+    () => getOrientationFromWindow(windowSize.width, windowSize.height),
+    [windowSize.width, windowSize.height],
+  );
+
+  // Get appropriate viewport preset
+  const viewport = useMemo(() => getViewportForOrientation(orientation), [orientation]);
+
+  return {
+    viewport,
+    orientation,
+    windowSize,
+  };
+}
+
+export default useViewportOrientation;

package/src/index.ts

@@ -0,0 +1,46 @@
+// Main components
+export { DocPlayer } from './DocPlayer.js';
+export { BlockRenderer, VIEWPORT } from './BlockRenderer.js';
+export { CaptionOverlay } from './CaptionOverlay.js';
+export { DocControlsOverlay } from './DocControlsOverlay.js';
+export { DocControlsBottom } from './DocControlsBottom.js';
+export { DocControlsSidebar } from './DocControlsSidebar.js';
+export { DocControlsSlideshow } from './DocControlsSlideshow.js';
+export { DocPlayerWithSidebar } from './DocPlayerWithSidebar.js';
+export { DocProgressBar } from './DocProgressBar.js';
+export { MarkdownRenderer } from './MarkdownRenderer.js';
+export { LinearDocView } from './LinearDocView.js';
+
+// Layer components
+export { ImageLayer } from './layers/ImageLayer.js';
+export { TextLayer } from './layers/TextLayer.js';
+export { ShapeLayer } from './layers/ShapeLayer.js';
+export { VideoLayer } from './layers/VideoLayer.js';
+export { MapLayer } from './layers/MapLayer.js';
+
+// Hooks
+export { useAudioSync } from './hooks/useAudioSync.js';
+export { useDocPlayback } from './hooks/useDocPlayback.js';
+export { useViewportOrientation } from './hooks/useViewportOrientation.js';
+export { MediaContext, useMediaProvider, useMediaUrl } from './hooks/MediaContext.js';
+
+// Types
+export type { AudioProvider, AudioState, AudioActions } from './hooks/AudioProvider.js';
+export type {
+  PlaybackState,
+  PlaybackActions,
+  BlockMarker,
+  ControlsLayout,
+  DisplayMode,
+  SlideNavActions,
+  SquisqRenderAPI,
+  SquisqWindow,
+  RenderBlockInfo,
+  RenderAudioSegmentInfo,
+  RenderCaptionInfo,
+  RenderChapterInfo,
+} from './types.js';
+export { formatTime } from './types.js';
+
+// Utilities
+export { getAnimationStyle, getTransitionClass } from './utils/animationUtils.js';

package/src/layers/ImageLayer.tsx

@@ -0,0 +1,182 @@
+/**
+ * ImageLayer Component
+ *
+ * Renders an image layer within an SVG block. Supports Ken Burns and other
+ * animations via CSS classes. Images are rendered using SVG <image> element
+ * with proper aspect ratio handling.
+ */
+
+import type { ImageLayer as ImageLayerType, Animation } from '@bendyline/squisq/schemas';
+import { getAnimationStyle } from '../utils/animationUtils';
+import { resolveValue, getAnchorOffset } from '../utils/layerUtils';
+import { useMediaUrl } from '../hooks/MediaContext';
+
+interface ImageLayerProps {
+  layer: ImageLayerType;
+  /** Base path for resolving relative image URLs */
+  basePath: string;
+  /** Viewport dimensions for percentage calculations */
+  viewport: { width: number; height: number };
+  /** Current time relative to block start (for animation timing) */
+  blockTime: number;
+}
+
+export function ImageLayer({ layer, basePath, viewport, blockTime }: ImageLayerProps) {
+  const { content, position, animation } = layer;
+
+  // Resolve position values to pixels
+  const x = resolveValue(position.x, viewport.width);
+  const y = resolveValue(position.y, viewport.height);
+  const width = position.width ? resolveValue(position.width, viewport.width) : viewport.width;
+  const height = position.height ? resolveValue(position.height, viewport.height) : viewport.height;
+
+  // Apply anchor offset
+  const offset = getAnchorOffset(position.anchor, width, height);
+  const finalX = x + offset.x;
+  const finalY = y + offset.y;
+
+  // Resolve image URL via MediaProvider (if available), falling back to basePath
+  const src = useMediaUrl(content.src, basePath);
+
+  // Get animation styles
+  const animStyle = getAnimationStyle(animation, blockTime);
+
+  // SVG preserveAspectRatio based on fit mode
+  const preserveAspectRatio = getPreserveAspectRatio(content.fit);
+  const isCover = content.fit === 'cover';
+
+  // Detect spatial (transform-based) animations that need Ken Burns treatment.
+  // These animations should move the image *content* within fixed bounds rather
+  // than shifting the entire image container.
+  const isSpatialAnim = animation && SPATIAL_ANIMATION_TYPES.has(animation.type);
+
+  // Ken Burns mode: cover image with spatial animation.
+  // Keep the container static, animate the inner <img> within clipped bounds.
+  if (isCover && isSpatialAnim && animation) {
+    const kbAnim = remapToKenBurns(animation);
+    const kbStyle = getAnimationStyle(kbAnim, blockTime);
+
+    return (
+      <g className="block-layer block-layer--image" data-layer-id={layer.id}>
+        <foreignObject x={finalX} y={finalY} width={width} height={height}>
+          <div
+            style={{
+              width: '100%',
+              height: '100%',
+              overflow: 'hidden',
+            }}
+          >
+            <img
+              src={src}
+              alt={content.alt || ''}
+              className={kbStyle.className}
+              style={{
+                width: '100%',
+                height: '100%',
+                objectFit: 'cover',
+                objectPosition: 'center',
+                display: 'block',
+                pointerEvents: 'none',
+                transformOrigin: 'center center',
+                ...kbStyle.style,
+              }}
+            />
+          </div>
+        </foreignObject>
+      </g>
+    );
+  }
+
+  // For cover mode, use foreignObject with CSS object-fit for more reliable coverage
+  // SVG's preserveAspectRatio can be inconsistent across browsers
+  if (isCover) {
+    return (
+      <g
+        className={`block-layer block-layer--image ${animStyle.className}`}
+        style={animStyle.style}
+        data-layer-id={layer.id}
+      >
+        <foreignObject x={finalX} y={finalY} width={width} height={height}>
+          <img
+            src={src}
+            alt={content.alt || ''}
+            style={{
+              width: '100%',
+              height: '100%',
+              objectFit: 'cover',
+              objectPosition: 'center',
+              display: 'block',
+              pointerEvents: 'none',
+            }}
+          />
+        </foreignObject>
+      </g>
+    );
+  }
+
+  // For contain/fill modes, use SVG image element
+  return (
+    <g
+      className={`block-layer block-layer--image ${animStyle.className}`}
+      style={animStyle.style}
+      data-layer-id={layer.id}
+    >
+      <image
+        href={src}
+        x={finalX}
+        y={finalY}
+        width={width}
+        height={height}
+        preserveAspectRatio={preserveAspectRatio}
+        style={{ pointerEvents: 'none' }}
+      />
+    </g>
+  );
+}
+
+/**
+ * Map fit mode to SVG preserveAspectRatio.
+ */
+function getPreserveAspectRatio(fit?: 'cover' | 'contain' | 'fill'): string {
+  switch (fit) {
+    case 'cover':
+      return 'xMidYMid slice';
+    case 'fill':
+      return 'none';
+    case 'contain':
+    default:
+      return 'xMidYMid meet';
+  }
+}
+
+// ============================================
+// Ken Burns Helpers
+// ============================================
+
+/** Animation types that use CSS transforms (translate/scale). */
+const SPATIAL_ANIMATION_TYPES = new Set(['panLeft', 'panRight', 'slowZoom', 'zoomIn', 'zoomOut']);
+
+/**
+ * Remap animation for Ken Burns inner-image rendering.
+ *
+ * Pure pan animations (panLeft/panRight) get remapped to combined slowZoom+pan
+ * to maintain minimum scale and avoid revealing gaps at image edges.
+ * zoomIn/zoomOut get remapped to slowZoom variants (no opacity change, which
+ * is inappropriate for sustained ambient motion).
+ */
+function remapToKenBurns(anim: Animation): Animation {
+  switch (anim.type) {
+    case 'panLeft':
+      return { ...anim, type: 'slowZoom', panDirection: 'left' };
+    case 'panRight':
+      return { ...anim, type: 'slowZoom', panDirection: 'right' };
+    case 'zoomIn':
+      return { ...anim, type: 'slowZoom', direction: 'in' };
+    case 'zoomOut':
+      return { ...anim, type: 'slowZoom', direction: 'out' };
+    default:
+      return anim; // slowZoom variants are already correct
+  }
+}
+
+export default ImageLayer;

package/src/layers/MapLayer.tsx

@@ -0,0 +1,184 @@
+/**
+ * MapLayer Component
+ *
+ * Renders a geographic map layer within an SVG block. Maps are composed from
+ * static tile images fetched from free/open-source providers.
+ *
+ * For video export reliability, maps can use pre-rendered static images via
+ * the staticSrc property, avoiding tile loading race conditions during capture.
+ *
+ * Tile fetching: Tiles are loaded on mount and composited into a data URL
+ * for SVG embedding. This ensures correct rendering in both browser and
+ * Playwright screenshot contexts.
+ */
+
+import { useState, useEffect } from 'react';
+import type { MapLayer as MapLayerType } from '@bendyline/squisq/schemas';
+import { getAnimationStyle } from '../utils/animationUtils';
+import { resolveValue, getAnchorOffset } from '../utils/layerUtils';
+import { composeMapImage } from '../utils/mapTileUtils';
+
+interface MapLayerProps {
+  layer: MapLayerType;
+  /** Base path for resolving relative image URLs */
+  basePath: string;
+  /** Viewport dimensions for percentage calculations */
+  viewport: { width: number; height: number };
+  /** Current time relative to block start (for animation timing) */
+  blockTime: number;
+}
+
+export function MapLayer({ layer, basePath, viewport, blockTime }: MapLayerProps) {
+  const { content, position, animation } = layer;
+  const [mapImageUrl, setMapImageUrl] = useState<string | null>(null);
+  const [isLoading, setIsLoading] = useState(true);
+  const [error, setError] = useState<string | null>(null);
+
+  // Resolve position values to pixels
+  const x = resolveValue(position.x, viewport.width);
+  const y = resolveValue(position.y, viewport.height);
+  const width = position.width ? resolveValue(position.width, viewport.width) : viewport.width;
+  const height = position.height ? resolveValue(position.height, viewport.height) : viewport.height;
+
+  // Apply anchor offset
+  const offset = getAnchorOffset(position.anchor, width, height);
+  const finalX = x + offset.x;
+  const finalY = y + offset.y;
+
+  // Use static image if provided, otherwise fetch and compose tiles
+  useEffect(() => {
+    let cancelled = false;
+
+    if (content.staticSrc) {
+      // Use pre-rendered static image
+      const src = content.staticSrc.startsWith('http')
+        ? content.staticSrc
+        : `${basePath}/${content.staticSrc}`;
+      setMapImageUrl(src);
+      setIsLoading(false);
+      return;
+    }
+
+    // Compose map from tiles
+    setIsLoading(true);
+    setError(null);
+
+    composeMapImage({
+      center: content.center,
+      zoom: content.zoom,
+      style: content.style,
+      width,
+      height,
+      markers: content.markers,
+      showAttribution: content.showAttribution !== false,
+    })
+      .then((dataUrl) => {
+        if (!cancelled) {
+          setMapImageUrl(dataUrl);
+          setIsLoading(false);
+        }
+      })
+      .catch((err: unknown) => {
+        if (!cancelled) {
+          console.error('Failed to compose map:', err);
+          setError(err instanceof Error ? err.message : String(err));
+          setIsLoading(false);
+        }
+      });
+
+    return () => {
+      cancelled = true;
+    };
+    // eslint-disable-next-line react-hooks/exhaustive-deps -- content properties are destructured below; center/markers/showAttribution are stable per-render
+  }, [
+    content.center.lat,
+    content.center.lng,
+    content.zoom,
+    content.style,
+    content.staticSrc,
+    width,
+    height,
+    basePath,
+  ]);
+
+  // Get animation styles
+  const animStyle = getAnimationStyle(animation, blockTime);
+
+  // Render loading state
+  if (isLoading) {
+    return (
+      <g
+        className={`block-layer block-layer--map ${animStyle.className}`}
+        style={animStyle.style}
+        data-layer-id={layer.id}
+      >
+        <rect x={finalX} y={finalY} width={width} height={height} fill="#e5e7eb" />
+        <text
+          x={finalX + width / 2}
+          y={finalY + height / 2}
+          textAnchor="middle"
+          dominantBaseline="middle"
+          fill="#9ca3af"
+          fontSize="24"
+          fontFamily="system-ui, sans-serif"
+        >
+          Loading map...
+        </text>
+      </g>
+    );
+  }
+
+  // Render error state
+  if (error || !mapImageUrl) {
+    return (
+      <g
+        className={`block-layer block-layer--map ${animStyle.className}`}
+        style={animStyle.style}
+        data-layer-id={layer.id}
+      >
+        <rect x={finalX} y={finalY} width={width} height={height} fill="#fef2f2" />
+        <text
+          x={finalX + width / 2}
+          y={finalY + height / 2}
+          textAnchor="middle"
+          dominantBaseline="middle"
+          fill="#dc2626"
+          fontSize="18"
+          fontFamily="system-ui, sans-serif"
+        >
+          Map failed to load
+        </text>
+      </g>
+    );
+  }
+
+  return (
+    <g
+      className={`block-layer block-layer--map ${animStyle.className}`}
+      style={animStyle.style}
+      data-layer-id={layer.id}
+    >
+      {/* Clip path for overflow handling */}
+      <defs>
+        <clipPath id={`clip-${layer.id}`}>
+          <rect x={finalX} y={finalY} width={width} height={height} />
+        </clipPath>
+      </defs>
+
+      {/* Map image */}
+      <g clipPath={`url(#clip-${layer.id})`}>
+        <image
+          href={mapImageUrl}
+          x={finalX}
+          y={finalY}
+          width={width}
+          height={height}
+          preserveAspectRatio="xMidYMid slice"
+          style={{ pointerEvents: 'none' }}
+        />
+      </g>
+    </g>
+  );
+}
+
+export default MapLayer;

package/src/layers/ShapeLayer.tsx

@@ -0,0 +1,107 @@
+/**
+ * ShapeLayer Component
+ *
+ * Renders simple geometric shapes (rect, circle, line) within an SVG block.
+ * Useful for visual accents, dividers, and background elements.
+ */
+
+import type { ShapeLayer as ShapeLayerType } from '@bendyline/squisq/schemas';
+import { getAnimationStyle } from '../utils/animationUtils';
+import { resolveValue } from '../utils/layerUtils';
+
+interface ShapeLayerProps {
+  layer: ShapeLayerType;
+  /** Viewport dimensions for percentage calculations */
+  viewport: { width: number; height: number };
+  /** Current time relative to block start */
+  blockTime: number;
+}
+
+export function ShapeLayer({ layer, viewport, blockTime }: ShapeLayerProps) {
+  const { content, position, animation } = layer;
+
+  // Resolve position values to pixels
+  const x = resolveValue(position.x, viewport.width);
+  const y = resolveValue(position.y, viewport.height);
+  const width = position.width ? resolveValue(position.width, viewport.width) : 100;
+  const height = position.height ? resolveValue(position.height, viewport.height) : 100;
+
+  // Get animation styles
+  const animStyle = getAnimationStyle(animation, blockTime);
+
+  // Check if fill is a CSS gradient (SVG rect doesn't support CSS gradients natively)
+  const fill = content.fill || 'none';
+  const isCSSGradient = typeof fill === 'string' && fill.includes('gradient(');
+
+  // For CSS gradients on rect, use foreignObject with an HTML div
+  if (content.shape === 'rect' && isCSSGradient) {
+    return (
+      <g
+        className={`block-layer block-layer--shape ${animStyle.className}`}
+        style={animStyle.style}
+        data-layer-id={layer.id}
+      >
+        <foreignObject x={x} y={y} width={width} height={height}>
+          <div
+            style={{
+              width: '100%',
+              height: '100%',
+              background: fill,
+              borderRadius: content.borderRadius ? `${content.borderRadius}px` : undefined,
+              pointerEvents: 'none',
+            }}
+          />
+        </foreignObject>
+      </g>
+    );
+  }
+
+  // Common style props for native SVG shapes
+  const shapeProps = {
+    fill: fill,
+    stroke: content.stroke,
+    strokeWidth: content.strokeWidth,
+  };
+
+  return (
+    <g
+      className={`block-layer block-layer--shape ${animStyle.className}`}
+      style={animStyle.style}
+      data-layer-id={layer.id}
+    >
+      {content.shape === 'rect' && (
+        <rect
+          x={x}
+          y={y}
+          width={width}
+          height={height}
+          rx={content.borderRadius}
+          ry={content.borderRadius}
+          {...shapeProps}
+        />
+      )}
+
+      {content.shape === 'circle' && (
+        <circle
+          cx={x + width / 2}
+          cy={y + height / 2}
+          r={Math.min(width, height) / 2}
+          {...shapeProps}
+        />
+      )}
+
+      {content.shape === 'line' && (
+        <line
+          x1={x}
+          y1={y}
+          x2={x + width}
+          y2={y + height}
+          stroke={content.stroke || '#ffffff'}
+          strokeWidth={content.strokeWidth || 2}
+        />
+      )}
+    </g>
+  );
+}
+
+export default ShapeLayer;