@bendyline/squisq-react 1.3.1 → 1.4.0

package/src/hooks/useDocPlayback.ts

@@ -12,14 +12,20 @@
  * - Automatic expansion of template blocks
  */
 
-import { useState, useEffect, useMemo, useCallback, useRef } from 'react';
+import { useMemo, useCallback, useRef } from 'react';
 import type { Doc, Block, DocBlock } from '@bendyline/squisq/schemas';
 import type { Theme } from '@bendyline/squisq/schemas';
-import { getBlockAtTime } from '@bendyline/squisq/schemas';
+import {
+  DEFAULT_THEME,
+  getBlockAtTime,
+  resolveBlockTransition,
+  resolveTransitionDuration,
+} from '@bendyline/squisq/schemas';
 import {
   expandDocBlocks,
-  flattenBlocks,
+  flattenRenderableBlocks,
   isTemplateBlock,
+  resolvePersistentLayers,
   VIEWPORT_PRESETS,
   type ViewportConfig,
 } from '@bendyline/squisq/doc';
@@ -61,29 +67,34 @@ export function useDocPlayback(
   renderMode: boolean = false,
   theme?: Theme,
 ): PlaybackState & PlaybackActions {
-  const [transitionState, setTransitionState] = useState<{
-    entering: boolean;
-    exiting: boolean;
-    previousBlock: Block | null;
-  }>({
-    entering: false,
-    exiting: false,
-    previousBlock: null,
-  });
-
+  // `renderMode` is retained for API/signature compatibility; block transitions
+  // are now computed identically for real-time and render (export) modes.
+  void renderMode;
   // Expand any template blocks into full blocks
   const blocks = useMemo(() => {
     if (!script?.blocks) {
       return [];
     }
 
-    // Flatten nested block hierarchy (markdown-derived docs have children)
+    // Flatten nested block hierarchy (markdown-derived docs have children).
+    // `flattenRenderableBlocks` skips the children of container templates
+    // (`diagram`, `drawing`) — those are consumed by the parent's render as
+    // nodes/shapes, so they must not also appear as their own slides.
     const hasChildren = script.blocks.some((b) => b.children && b.children.length > 0);
-    const flatBlocks = hasChildren ? flattenBlocks(script.blocks) : script.blocks;
+    const flatBlocks = hasChildren ? flattenRenderableBlocks(script.blocks) : script.blocks;
 
     // Check if any blocks are templates
     const hasTemplates = flatBlocks.some(isTemplateBlock);
 
+    // Doc persistent layers win wholesale; docs without any inherit the
+    // theme's (see resolvePersistentLayers). Passed as a narrow object so
+    // the memo deps stay field-precise.
+    const resolvedTheme = theme ?? DEFAULT_THEME;
+    const persistentLayers = resolvePersistentLayers(
+      { persistentLayers: script.persistentLayers },
+      resolvedTheme,
+    );
+
     if (hasTemplates) {
       // Extract audio segment timing for proper block synchronization
       const audioSegments = script.audio?.segments?.map((seg) => ({
@@ -95,15 +106,31 @@ export function useDocPlayback(
       const expanded = expandDocBlocks(flatBlocks as DocBlock[], {
         audioSegments,
         viewport,
-        persistentLayers: script.persistentLayers,
+        persistentLayers,
         theme,
+        // Custom (user-defined) templates inlined into the doc's
+        // frontmatter — see CustomTemplates.ts. Merged onto the
+        // built-in registry so blocks annotated with `{[myhero]}`
+        // resolve through the user's design.
+        customTemplates: script.customTemplates,
       });
       return expanded;
     }
 
-    // All raw blocks, use as-is
-    return flatBlocks;
-  }, [script?.blocks, script?.audio?.segments, script?.persistentLayers, viewport, theme]);
+    // All raw blocks — used as-is except for the theme's default transition
+    // fallback (copies, never mutations: these blocks are caller-owned).
+    return flatBlocks.map((block, index) => {
+      const transition = resolveBlockTransition(block, resolvedTheme, index);
+      return transition !== block.transition ? { ...block, transition } : block;
+    });
+  }, [
+    script?.blocks,
+    script?.audio?.segments,
+    script?.persistentLayers,
+    script?.customTemplates,
+    viewport,
+    theme,
+  ]);
 
   // Find current block based on time
   const currentBlock = useMemo(() => getBlockAtTime(blocks, currentTime), [blocks, currentTime]);
@@ -130,78 +157,38 @@ export function useDocPlayback(
     return Math.min(1, currentTime / script.duration);
   }, [script, currentTime]);
 
-  // Track block transitions.
-  // In render mode, transitions are computed from blockTime so they stay
-  // synchronized with the seekTo timeline. In normal mode, setTimeout drives
-  // transitions at the browser's real-time clock speed.
-  const _prevBlockRef = useMemo(
-    () => currentBlock,
-    // eslint-disable-next-line react-hooks/exhaustive-deps -- intentionally keyed on index, not block reference
-    [currentBlockIndex],
-  );
-
-  useEffect(() => {
-    if (!currentBlock || renderMode) return;
-
-    // When block changes, trigger transition (real-time mode only)
-    if (transitionState.previousBlock?.id !== currentBlock.id) {
-      const transition = currentBlock.transition;
-      const transitionDuration = transition?.duration || 0;
-
-      if (transitionDuration > 0) {
-        // Start transition
-        setTransitionState({
-          entering: true,
-          exiting: true,
-          previousBlock: transitionState.previousBlock,
-        });
-
-        // End transition after duration
-        const timer = setTimeout(() => {
-          setTransitionState({
-            entering: false,
-            exiting: false,
-            previousBlock: currentBlock,
-          });
-        }, transitionDuration * 1000);
-
-        return () => clearTimeout(timer);
-      } else {
-        // Instant cut
-        setTransitionState({
-          entering: false,
-          exiting: false,
-          previousBlock: currentBlock,
-        });
-      }
-    }
-    // eslint-disable-next-line react-hooks/exhaustive-deps -- intentionally keyed on currentBlock?.id only; reading transitionState.previousBlock without dep to avoid infinite loop
-  }, [currentBlock?.id, renderMode]);
-
-  // Render mode: track previous block via ref and compute transition from time
-  const renderPrevBlockRef = useRef<Block | null>(null);
-
-  useEffect(() => {
-    if (!renderMode || !currentBlock) return;
-
-    if (transitionState.previousBlock?.id !== currentBlock.id) {
-      // Block changed — remember the old block for crossfade
-      const oldPrev = transitionState.previousBlock;
-      renderPrevBlockRef.current = oldPrev;
-      // Store current block as the "last seen" for next transition
-      setTransitionState((prev) => ({
-        ...prev,
-        previousBlock: currentBlock,
-      }));
-    }
-    // eslint-disable-next-line react-hooks/exhaustive-deps -- same pattern: keyed on block identity change
-  }, [currentBlock?.id, renderMode]);
-
-  // In render mode, derive entering/exiting from blockTime
-  const renderTransitionDuration = currentBlock?.transition?.duration || 0;
-  const renderIsEntering =
-    renderMode && renderTransitionDuration > 0 && blockTime < renderTransitionDuration;
-  const renderIsExiting = renderIsEntering && renderPrevBlockRef.current !== null;
+  // ─── Transition tracking (synchronous — no effect lag) ──────────────
+  // `isEntering` is simply "we are within the block's entrance window"
+  // (blockTime < the transition's duration). Deriving it during render —
+  // rather than flipping it in an effect a frame AFTER the block changes —
+  // means a newly-active block renders WITH its entrance state on its very
+  // first frame. Otherwise the block paints once fully settled and then, a
+  // frame later, snaps back to the start of its entrance animation: the brief
+  // "flash then re-animate" seen between blocks. This runs identically for
+  // real-time playback and frame-seeked render (export) mode.
+  //
+  // The block we transitioned FROM (for the crossfade) is tracked with refs
+  // updated during render — the standard "previous value" pattern — so the
+  // outgoing block is known on the SAME frame the new block becomes active
+  // (an effect would lag a frame and drop the crossfade's first frames).
+  const outgoingBlockRef = useRef<Block | null>(null);
+  const activeBlockIdRef = useRef<string | null>(null);
+  const lastRenderedBlockRef = useRef<Block | null>(null);
+  if (currentBlock && currentBlock.id !== activeBlockIdRef.current) {
+    outgoingBlockRef.current = lastRenderedBlockRef.current;
+    activeBlockIdRef.current = currentBlock.id;
+  }
+  lastRenderedBlockRef.current = currentBlock;
+
+  const transitionDuration = currentBlock?.transition
+    ? resolveTransitionDuration(currentBlock.transition)
+    : 0;
+  const isEntering = !!currentBlock && transitionDuration > 0 && blockTime < transitionDuration;
+  const outgoingBlock = outgoingBlockRef.current;
+  // Only crossfade a genuinely different outgoing block (guards restarts/seeks
+  // where the "previous" resolves to the same block).
+  const isExiting = isEntering && outgoingBlock != null && outgoingBlock.id !== currentBlock?.id;
+  const previousBlock = isExiting ? outgoingBlock : null;
 
   // Manual navigation
   const goToBlock = useCallback(
@@ -233,15 +220,9 @@ export function useDocPlayback(
   return {
     currentBlock,
     currentBlockIndex,
-    previousBlock: renderMode
-      ? renderIsExiting
-        ? renderPrevBlockRef.current
-        : null
-      : transitionState.exiting
-        ? transitionState.previousBlock
-        : null,
-    isEntering: renderMode ? renderIsEntering : transitionState.entering,
-    isExiting: renderMode ? renderIsExiting : transitionState.exiting,
+    previousBlock,
+    isEntering,
+    isExiting,
     blockTime,
     blockProgress,
     docProgress,

package/src/hooks/useMediaSchedule.ts

@@ -0,0 +1,39 @@
+/**
+ * useMediaSchedule
+ *
+ * Pure follower of the playback clock for the media-clip model. Given the
+ * resolved {@link ScheduledClip}s and the current time, it returns the clips
+ * the player should mount and which of them are active right now.
+ * {@link MediaClipLayer} consumes this to drive one hidden `<audio>` /
+ * full-bleed `<video>` element per clip. (Annotation-authored clips all render
+ * at the player level; template-produced `VideoLayer`s are a separate path and
+ * are not part of the schedule.)
+ *
+ * It owns no clock: `currentTime`/`isPlaying` come from the existing
+ * `useAudioSync` provider via `DocPlayer`. With an empty schedule it returns
+ * empty lists, so documents without the new media model are unaffected.
+ */
+
+import { useMemo } from 'react';
+import type { ScheduledClip } from '@bendyline/squisq/schemas';
+
+export interface MediaScheduleController {
+  /** Clips the player mounts (every scheduled clip). */
+  renderClips: ScheduledClip[];
+  /** Ids of clips whose [absoluteStart, absoluteEnd) contains currentTime. */
+  activeIds: Set<string>;
+}
+
+export function useMediaSchedule(
+  schedule: ScheduledClip[],
+  currentTime: number,
+): MediaScheduleController {
+  const activeIds = useMemo(() => {
+    const ids = new Set<string>();
+    for (const c of schedule) {
+      if (currentTime >= c.absoluteStart && currentTime < c.absoluteEnd) ids.add(c.id);
+    }
+    return ids;
+  }, [schedule, currentTime]);
+  return { renderClips: schedule, activeIds };
+}

package/src/index.ts

@@ -21,12 +21,19 @@ export type { InlineAudioPlayerProps } from './InlineAudioPlayer.js';
 export { ImageLayer } from './layers/ImageLayer.js';
 export { TextLayer } from './layers/TextLayer.js';
 export { ShapeLayer } from './layers/ShapeLayer.js';
+export { PathLayer } from './layers/PathLayer.js';
 export { VideoLayer } from './layers/VideoLayer.js';
 export { TableLayer } from './layers/TableLayer.js';
 export { MapLayer } from './layers/MapLayer.js';
 
+// Timed media clips (block.media + doc.documentMedia playback)
+export { MediaClipLayer } from './MediaClipLayer.js';
+export type { MediaClipLayerProps } from './MediaClipLayer.js';
+
 // Hooks
 export { useAudioSync } from './hooks/useAudioSync.js';
+export { useMediaSchedule } from './hooks/useMediaSchedule.js';
+export type { MediaScheduleController } from './hooks/useMediaSchedule.js';
 export { useDocPlayback } from './hooks/useDocPlayback.js';
 export { useViewportOrientation } from './hooks/useViewportOrientation.js';
 export { MediaContext, useMediaProvider, useMediaUrl } from './hooks/MediaContext.js';

package/src/layers/ImageLayer.tsx

@@ -7,6 +7,7 @@
  */
 
 import type { ImageLayer as ImageLayerType, Animation } from '@bendyline/squisq/schemas';
+import { cssFilterForTreatment } from '@bendyline/squisq/doc';
 import { getAnimationStyle } from '../utils/animationUtils';
 import { resolveValue, getAnchorOffset } from '../utils/layerUtils';
 import { useMediaUrl } from '../hooks/MediaContext';
@@ -41,6 +42,10 @@ export function ImageLayer({ layer, basePath, viewport, blockTime }: ImageLayerP
   // Get animation styles
   const animStyle = getAnimationStyle(animation, blockTime);
 
+  // Theme-derived photographic grade + optional blur, as a CSS filter
+  // string (identical in the player and in headless frame capture).
+  const filter = cssFilterForTreatment(content.treatment, content.blur);
+
   // SVG preserveAspectRatio based on fit mode
   const preserveAspectRatio = getPreserveAspectRatio(content.fit);
   const isCover = content.fit === 'cover';
@@ -78,6 +83,7 @@ export function ImageLayer({ layer, basePath, viewport, blockTime }: ImageLayerP
                 display: 'block',
                 pointerEvents: 'none',
                 transformOrigin: 'center center',
+                ...(filter ? { filter } : {}),
                 ...kbStyle.style,
               }}
             />
@@ -107,6 +113,10 @@ export function ImageLayer({ layer, basePath, viewport, blockTime }: ImageLayerP
               objectPosition: 'center',
               display: 'block',
               pointerEvents: 'none',
+              ...(filter ? { filter } : {}),
+              // Over-scan blurred imagery so the soft edges never reveal
+              // the frame behind the layer.
+              ...(content.blur && content.blur > 0 ? { transform: 'scale(1.06)' } : {}),
             }}
           />
         </foreignObject>
@@ -128,7 +138,7 @@ export function ImageLayer({ layer, basePath, viewport, blockTime }: ImageLayerP
         width={width}
         height={height}
         preserveAspectRatio={preserveAspectRatio}
-        style={{ pointerEvents: 'none' }}
+        style={{ pointerEvents: 'none', ...(filter ? { filter } : {}) }}
       />
     </g>
   );

package/src/layers/PathLayer.tsx

@@ -0,0 +1,146 @@
+/**
+ * PathLayer Component
+ *
+ * Renders an SVG `<path>` for arbitrary curves, connectors, arrows, and the
+ * drawing template's computed shapes. Used by the diagram template for edges
+ * between nodes; usable by any template that needs a non-rect/circle/line
+ * shape.
+ *
+ * The path's `d` attribute uses absolute SVG coordinates relative to the
+ * block viewport (independent of the layer's `position` box, which is
+ * present only so animations and clipping match the other layer types).
+ *
+ * Exception: when `content.shapeKind` is set (a standard named shape like
+ * `diamond` / `star` / `arrow-right`), `d` is re-derived from the layer's
+ * `position` box resolved against the viewport. That keeps named shapes
+ * movable, resizable, and aspect-ratio-adaptive — matching how the native
+ * rect/circle/line `ShapeLayer` behaves — rather than pinned to a baked
+ * absolute path.
+ *
+ * End markers are configured via `startMarker`/`endMarker` (with the legacy
+ * `arrow` flag mapping to a filled triangle). Marker geometry comes from
+ * `markerPath` in core so the SSR renderer and the editor agree.
+ */
+
+import type { PathLayer as PathLayerType, MarkerStyle } from '@bendyline/squisq/schemas';
+import { markerPath, shapePath } from '@bendyline/squisq/doc';
+import { getAnimationStyle } from '../utils/animationUtils';
+import { resolveValue, getAnchorOffset } from '../utils/layerUtils';
+import { resolveFill, borderDashArray } from '../utils/fillStyle';
+
+interface PathLayerProps {
+  layer: PathLayerType;
+  /** Viewport dimensions — used to resolve `%` positions for named shapes. */
+  viewport: { width: number; height: number };
+  /** Current time relative to block start. */
+  blockTime: number;
+}
+
+/**
+ * The effective `d`: a named shape (`content.shapeKind`) is re-derived
+ * from the resolved `position` box so it tracks moves/resizes and adapts
+ * to the viewport; everything else uses the stored absolute path.
+ */
+function effectivePath(layer: PathLayerType, viewport: { width: number; height: number }): string {
+  const { content, position } = layer;
+  if (!content.shapeKind) return content.d;
+  const w = position.width ? resolveValue(position.width, viewport.width) : 0;
+  const h = position.height ? resolveValue(position.height, viewport.height) : 0;
+  const rawX = resolveValue(position.x, viewport.width);
+  const rawY = resolveValue(position.y, viewport.height);
+  const anchor = getAnchorOffset(position.anchor, w, h);
+  const derived = shapePath(content.shapeKind, rawX + anchor.x, rawY + anchor.y, w, h);
+  // Fall back to the stored path if the kind is unknown to `shapePath`.
+  return derived ?? content.d;
+}
+
+/** Resolve the effective marker for an endpoint (explicit field, else `arrow`). */
+function effectiveMarker(
+  explicit: MarkerStyle | undefined,
+  arrow: PathLayerType['content']['arrow'],
+  end: 'start' | 'end',
+): MarkerStyle {
+  if (explicit) return explicit;
+  const wants = arrow === 'both' || arrow === end;
+  return wants ? 'arrow' : 'none';
+}
+
+export function PathLayer({ layer, viewport, blockTime }: PathLayerProps) {
+  const { content, animation, id } = layer;
+  const d = effectivePath(layer, viewport);
+  const stroke = content.stroke ?? '#1e293b';
+  const strokeWidth = content.strokeWidth ?? 2;
+  const { fill, def: fillDef } = resolveFill(id, content.fill ?? 'none', content.gradient);
+  // `borderStyle` (named shapes) takes precedence over a raw `dasharray`.
+  const dash = content.borderStyle
+    ? borderDashArray(content.borderStyle, strokeWidth)
+    : content.dasharray;
+  const animStyle = getAnimationStyle(animation, blockTime);
+
+  const startId = `marker-start-${id}`;
+  const endId = `marker-end-${id}`;
+  const start = markerPath(effectiveMarker(content.startMarker, content.arrow, 'start'), 'start');
+  const end = markerPath(effectiveMarker(content.endMarker, content.arrow, 'end'), 'end');
+
+  return (
+    <g
+      className={`block-layer block-layer--path ${animStyle.className}`}
+      style={animStyle.style}
+      data-layer-id={id}
+    >
+      <defs>
+        {fillDef}
+        {end && <MarkerDef id={endId} dir="end" d={end.d} filled={end.filled} stroke={stroke} />}
+        {start && (
+          <MarkerDef id={startId} dir="start" d={start.d} filled={start.filled} stroke={stroke} />
+        )}
+      </defs>
+      <path
+        d={d}
+        stroke={stroke}
+        strokeWidth={strokeWidth}
+        fill={fill}
+        fillOpacity={content.fillOpacity}
+        strokeDasharray={dash}
+        markerStart={start ? `url(#${startId})` : undefined}
+        markerEnd={end ? `url(#${endId})` : undefined}
+      />
+    </g>
+  );
+}
+
+function MarkerDef({
+  id,
+  dir,
+  d,
+  filled,
+  stroke,
+}: {
+  id: string;
+  dir: 'start' | 'end';
+  d: string;
+  filled: boolean;
+  stroke: string;
+}) {
+  return (
+    <marker
+      id={id}
+      viewBox="0 0 10 10"
+      refX={dir === 'end' ? 9 : 1}
+      refY={5}
+      markerWidth={4}
+      markerHeight={4}
+      orient="auto-start-reverse"
+      markerUnits="strokeWidth"
+    >
+      <path
+        d={d}
+        fill={filled ? stroke : 'none'}
+        stroke={filled ? 'none' : stroke}
+        strokeWidth={filled ? undefined : 1.5}
+      />
+    </marker>
+  );
+}
+
+export default PathLayer;

package/src/layers/ShapeLayer.tsx

@@ -8,6 +8,7 @@
 import type { ShapeLayer as ShapeLayerType } from '@bendyline/squisq/schemas';
 import { getAnimationStyle } from '../utils/animationUtils';
 import { resolveValue, getAnchorOffset } from '../utils/layerUtils';
+import { resolveFill, resolveShapeFilter, borderDashArray } from '../utils/fillStyle';
 
 interface ShapeLayerProps {
   layer: ShapeLayerType;
@@ -34,12 +35,14 @@ export function ShapeLayer({ layer, viewport, blockTime }: ShapeLayerProps) {
   // 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';
+  // Legacy: a CSS gradient string baked into `fill` (e.g. from older docs)
+  // only works as an HTML background, so rect renders it via foreignObject.
+  // The structured `content.gradient` (preferred) is handled below for all
+  // shapes via an SVG <linearGradient>.
   const isCSSGradient = typeof fill === 'string' && fill.includes('gradient(');
 
-  // For CSS gradients on rect, use foreignObject with an HTML div
-  if (content.shape === 'rect' && isCSSGradient) {
+  if (content.shape === 'rect' && isCSSGradient && !content.gradient) {
     return (
       <g
         className={`block-layer block-layer--shape ${animStyle.className}`}
@@ -61,11 +64,23 @@ export function ShapeLayer({ layer, viewport, blockTime }: ShapeLayerProps) {
     );
   }
 
-  // Common style props for native SVG shapes
+  const { fill: fillValue, def: fillDef } = resolveFill(
+    layer.id,
+    fill,
+    content.gradient,
+    content.pattern,
+  );
+  const { filterAttr, def: filterDef } = resolveShapeFilter(layer.id, content.filter);
+  const dash = borderDashArray(content.borderStyle, content.strokeWidth);
+
+  // Common style props for native SVG shapes. `line` is stroke-only.
   const shapeProps = {
-    fill: fill,
+    fill: fillValue,
+    fillOpacity: content.fillOpacity,
     stroke: content.stroke,
     strokeWidth: content.strokeWidth,
+    strokeDasharray: dash,
+    ...(filterAttr ? { filter: filterAttr } : {}),
   };
 
   return (
@@ -74,6 +89,12 @@ export function ShapeLayer({ layer, viewport, blockTime }: ShapeLayerProps) {
       style={animStyle.style}
       data-layer-id={layer.id}
     >
+      {(fillDef || filterDef) && (
+        <defs>
+          {fillDef}
+          {filterDef}
+        </defs>
+      )}
       {content.shape === 'rect' && (
         <rect
           x={x}
@@ -103,6 +124,7 @@ export function ShapeLayer({ layer, viewport, blockTime }: ShapeLayerProps) {
           y2={y + height}
           stroke={content.stroke || '#ffffff'}
           strokeWidth={content.strokeWidth || 2}
+          strokeDasharray={dash}
         />
       )}
     </g>