@bendyline/squisq-react 1.3.1 → 1.4.0

package/src/__tests__/DocProgressBar.test.tsx

@@ -0,0 +1,76 @@
+import { describe, it, expect } from 'vitest';
+import { render } from '@testing-library/react';
+import { DocProgressBar } from '../DocProgressBar';
+import type { PlaybackState, PlaybackActions } from '../types';
+
+function makeState(overrides: Partial<PlaybackState> = {}): PlaybackState {
+  return {
+    isPlaying: true,
+    currentTime: 0,
+    totalDuration: 60,
+    currentBlockIndex: 0,
+    totalBlocks: 3,
+    docProgress: 0,
+    hasCaptions: false,
+    captionsEnabled: false,
+    captionMode: 'off',
+    currentSegmentIndex: 0,
+    currentSegmentName: null,
+    currentBlock: null,
+    ...overrides,
+  };
+}
+
+const actions: PlaybackActions = {
+  toggle: () => {},
+  restart: () => {},
+  seekTo: () => {},
+  setCaptionsEnabled: () => {},
+  cycleCaptionMode: () => {},
+};
+
+/** The progress fill is the div tagged `doc-progress-fill`. */
+function fillWidth(container: HTMLElement): string {
+  const fill = container.querySelector<HTMLElement>('[data-testid="doc-progress-fill"]');
+  if (!fill) throw new Error('progress fill not found');
+  return fill.style.width;
+}
+
+describe('DocProgressBar fill', () => {
+  it('tracks elapsed time over totalDuration (the clock/marker timeline)', () => {
+    const { container } = render(
+      <DocProgressBar
+        state={makeState({ currentTime: 12, totalDuration: 23, docProgress: 0.99 })}
+        actions={actions}
+        blockMarkers={[]}
+        expandedBlocks={[]}
+      />,
+    );
+    // Must reflect 12/23 ≈ 52%, NOT the divergent docProgress (0.99).
+    expect(fillWidth(container)).toBe(`${(12 / 23) * 100}%`);
+  });
+
+  it('is 0% when totalDuration is 0 (no divide-by-zero)', () => {
+    const { container } = render(
+      <DocProgressBar
+        state={makeState({ currentTime: 5, totalDuration: 0, docProgress: 0.5 })}
+        actions={actions}
+        blockMarkers={[]}
+        expandedBlocks={[]}
+      />,
+    );
+    expect(fillWidth(container)).toBe('0%');
+  });
+
+  it('clamps to 100% when currentTime exceeds totalDuration', () => {
+    const { container } = render(
+      <DocProgressBar
+        state={makeState({ currentTime: 30, totalDuration: 23 })}
+        actions={actions}
+        blockMarkers={[]}
+        expandedBlocks={[]}
+      />,
+    );
+    expect(fillWidth(container)).toBe('100%');
+  });
+});

package/src/__tests__/MarkdownRenderer.test.tsx

@@ -1,7 +1,11 @@
 import { describe, it, expect } from 'vitest';
 import { render } from '@testing-library/react';
 import { MarkdownRenderer } from '../MarkdownRenderer';
-import type { MarkdownBlockNode, MarkdownInlineNode } from '@bendyline/squisq/markdown';
+import {
+  parseMarkdown,
+  type MarkdownBlockNode,
+  type MarkdownInlineNode,
+} from '@bendyline/squisq/markdown';
 
 // ── Helpers ────────────────────────────────────────────────────────
 
@@ -20,6 +24,10 @@ function heading(
   return { type: 'heading', depth, children };
 }
 
+function parseNodes(markdown: string): MarkdownBlockNode[] {
+  return parseMarkdown(markdown).children;
+}
+
 // ── Tests ──────────────────────────────────────────────────────────
 
 describe('MarkdownRenderer', () => {
@@ -85,6 +93,15 @@ describe('MarkdownRenderer', () => {
     expect(a.textContent).toBe('click');
   });
 
+  it('renders unsafe links as inert text by default', () => {
+    const { container } = render(
+      <MarkdownRenderer nodes={parseNodes('[x](javascript:alert(1))')} />,
+    );
+    expect(container.querySelector('a.squisq-md-link')).toBeNull();
+    expect(container.querySelector('.squisq-md-link--blocked')?.textContent).toBe('x');
+    expect(container.innerHTML).not.toContain('javascript:');
+  });
+
   it('renders an image', () => {
     const nodes: MarkdownBlockNode[] = [
       paragraph({
@@ -231,4 +248,81 @@ describe('MarkdownRenderer', () => {
     );
     expect(container.querySelector('.squisq-md.custom')).toBeTruthy();
   });
+
+  it('sanitizes raw HTML by default', () => {
+    const nodes = parseNodes(
+      '<div><img src="x.jpg" onerror="alert(1)"><script>alert(1)</script><span onclick="alert(1)">ok</span></div>',
+    );
+    const { container } = render(<MarkdownRenderer nodes={nodes} />);
+
+    expect(container.querySelector('script')).toBeNull();
+    expect(container.querySelector('img')?.getAttribute('src')).toBe('x.jpg');
+    expect(container.querySelector('img')?.getAttribute('onerror')).toBeNull();
+    expect(container.querySelector('span')?.getAttribute('onclick')).toBeNull();
+    expect(container.textContent).toContain('ok');
+    expect(container.textContent).not.toContain('alert(1)');
+  });
+
+  it('strips raw HTML when requested', () => {
+    const { container } = render(
+      <MarkdownRenderer nodes={parseNodes('<div><span>hidden</span></div>')} htmlPolicy="strip" />,
+    );
+    expect(container.textContent).not.toContain('hidden');
+    expect(container.querySelector('span')).toBeNull();
+  });
+
+  it('preserves raw HTML only with the trusted opt-in', () => {
+    const { container } = render(
+      <MarkdownRenderer
+        nodes={parseNodes('<div><span class="trusted" onclick="alert(1)">ok</span></div>')}
+        htmlPolicy="trusted"
+      />,
+    );
+    const span = container.querySelector('span.trusted');
+    expect(span?.getAttribute('onclick')).toBe('alert(1)');
+  });
+
+  // Host-affecting tags (style/script/…) must never reach the document.
+  // A bare <style> applies page-wide (CSS isn't scoped outside shadow DOM
+  // / iframes), so an embedded game's <style> in a chat message used to
+  // restyle the whole app chrome. Guard it across every policy.
+  it('drops a raw <style> by default so it cannot leak onto the host', () => {
+    const { container } = render(
+      <MarkdownRenderer
+        nodes={parseNodes('<div><style>body{font-family:monospace}</style><p>hi</p></div>')}
+      />,
+    );
+    expect(container.querySelector('style')).toBeNull();
+    expect(container.textContent).toContain('hi');
+    expect(container.textContent).not.toContain('font-family');
+  });
+
+  it('drops <style>/<script> even under the trusted policy, keeping safe content', () => {
+    const { container } = render(
+      <MarkdownRenderer
+        nodes={parseNodes(
+          '<div class="game"><style>body{font-family:monospace}</style><script>alert(1)</script><p>play</p></div>',
+        )}
+        htmlPolicy="trusted"
+      />,
+    );
+    expect(container.querySelector('style')).toBeNull();
+    expect(container.querySelector('script')).toBeNull();
+    expect(container.querySelector('div.game')).toBeTruthy();
+    expect(container.textContent).toContain('play');
+    expect(container.textContent).not.toContain('font-family');
+  });
+
+  it('drops a raw <style> on the verbatim path when htmlChildren was not parsed', () => {
+    // parseHtml:false leaves htmlChildren empty while rawHtml keeps the
+    // markup — the raw-string backstop must still refuse the fast path.
+    const node = {
+      type: 'htmlBlock',
+      rawHtml: '<style>body{font-family:monospace}</style><p>play</p>',
+      htmlChildren: [],
+    } as unknown as MarkdownBlockNode;
+    const { container } = render(<MarkdownRenderer nodes={[node]} htmlPolicy="trusted" />);
+    expect(container.querySelector('style')).toBeNull();
+    expect(container.textContent).not.toContain('font-family');
+  });
 });

package/src/__tests__/PathLayer.test.tsx

@@ -0,0 +1,73 @@
+import { describe, it, expect } from 'vitest';
+import { render } from '@testing-library/react';
+import { PathLayer } from '../layers/PathLayer';
+import type { PathLayer as PathLayerType } from '@bendyline/squisq/schemas';
+
+const viewport = { width: 1000, height: 1000 };
+
+function renderPath(layer: PathLayerType) {
+  const { container } = render(
+    <svg>
+      <PathLayer layer={layer} viewport={viewport} blockTime={0} />
+    </svg>,
+  );
+  return container.querySelector('path')!;
+}
+
+describe('PathLayer', () => {
+  it('uses the stored absolute `d` for plain paths (no shapeKind)', () => {
+    const path = renderPath({
+      id: 'p1',
+      type: 'path',
+      position: { x: 0, y: 0, width: 100, height: 100 },
+      content: { d: 'M 10 10 L 90 90' },
+    });
+    expect(path.getAttribute('d')).toBe('M 10 10 L 90 90');
+  });
+
+  it('derives `d` from the position box for a named shape', () => {
+    // A diamond's first vertex is the top-center of its box.
+    const path = renderPath({
+      id: 'p2',
+      type: 'path',
+      position: { x: 100, y: 200, width: 400, height: 200 },
+      content: { d: 'STALE', shapeKind: 'diamond' },
+    });
+    const d = path.getAttribute('d')!;
+    expect(d).not.toBe('STALE');
+    // Top vertex at (x + w/2, y) = (300, 200).
+    expect(d.startsWith('M 300 200')).toBe(true);
+  });
+
+  it('moving the position moves a named shape (regenerates `d`)', () => {
+    const at = (x: number) =>
+      renderPath({
+        id: 'p3',
+        type: 'path',
+        position: { x, y: 0, width: 200, height: 200 },
+        content: { d: 'M 0 0', shapeKind: 'diamond' },
+      }).getAttribute('d')!;
+    expect(at(0)).not.toBe(at(300));
+  });
+
+  it('resolves `%` positions against the viewport', () => {
+    const path = renderPath({
+      id: 'p4',
+      type: 'path',
+      position: { x: '0%', y: '0%', width: '50%', height: '50%' },
+      content: { d: '', shapeKind: 'diamond' },
+    });
+    // 50% of a 1000px viewport → 500px box; diamond top vertex at (250, 0).
+    expect(path.getAttribute('d')!.startsWith('M 250 0')).toBe(true);
+  });
+
+  it('falls back to the stored `d` when shapeKind is unknown', () => {
+    const path = renderPath({
+      id: 'p5',
+      type: 'path',
+      position: { x: 0, y: 0, width: 100, height: 100 },
+      content: { d: 'M 1 2 L 3 4', shapeKind: 'not-a-real-shape' },
+    });
+    expect(path.getAttribute('d')).toBe('M 1 2 L 3 4');
+  });
+});

package/src/__tests__/fillStyle.test.tsx

@@ -0,0 +1,112 @@
+import { describe, it, expect } from 'vitest';
+import { render } from '@testing-library/react';
+import { borderDashArray, resolveFill } from '../utils/fillStyle';
+import { ShapeLayer } from '../layers/ShapeLayer';
+import { TextLayer } from '../layers/TextLayer';
+import type {
+  ShapeLayer as ShapeLayerType,
+  TextLayer as TextLayerType,
+} from '@bendyline/squisq/schemas';
+
+const viewport = { width: 1000, height: 1000 };
+
+describe('borderDashArray', () => {
+  it('returns undefined for solid / unset', () => {
+    expect(borderDashArray(undefined, 2)).toBeUndefined();
+    expect(borderDashArray('solid', 2)).toBeUndefined();
+  });
+  it('scales the pattern by stroke width', () => {
+    expect(borderDashArray('dashed', 2)).toBe('6 4');
+    expect(borderDashArray('dotted', 2)).toBe('2 4');
+  });
+});
+
+describe('resolveFill', () => {
+  it('returns the solid color with no def when there is no gradient', () => {
+    const { fill, def } = resolveFill('x', '#abcdef', undefined);
+    expect(fill).toBe('#abcdef');
+    expect(def).toBeNull();
+  });
+  it('returns a url() fill and a gradient def when a gradient is set', () => {
+    const { fill, def } = resolveFill('x', '#abcdef', { from: '#000', to: '#fff', angle: 90 });
+    expect(fill).toBe('url(#squisq-grad-x)');
+    expect(def).not.toBeNull();
+  });
+});
+
+describe('ShapeLayer fill/border', () => {
+  function makeShape(content: Partial<ShapeLayerType['content']>): ShapeLayerType {
+    return {
+      id: 's1',
+      type: 'shape',
+      position: { x: 0, y: 0, width: 100, height: 100 },
+      content: { shape: 'rect', ...content },
+    } as ShapeLayerType;
+  }
+
+  it('applies fill opacity and a dashed border', () => {
+    const { container } = render(
+      <svg>
+        <ShapeLayer
+          layer={makeShape({
+            fill: '#3b82f6',
+            fillOpacity: 0.5,
+            stroke: '#000',
+            strokeWidth: 4,
+            borderStyle: 'dashed',
+          })}
+          viewport={viewport}
+          blockTime={0}
+        />
+      </svg>,
+    );
+    const rect = container.querySelector('rect')!;
+    expect(rect.getAttribute('fill-opacity')).toBe('0.5');
+    expect(rect.getAttribute('stroke-dasharray')).toBe('12 8');
+  });
+
+  it('renders a gradient via an SVG linearGradient', () => {
+    const { container } = render(
+      <svg>
+        <ShapeLayer
+          layer={makeShape({ gradient: { from: '#111', to: '#eee', angle: 0 } })}
+          viewport={viewport}
+          blockTime={0}
+        />
+      </svg>,
+    );
+    expect(container.querySelector('linearGradient')).not.toBeNull();
+    expect(container.querySelector('rect')!.getAttribute('fill')).toBe('url(#squisq-grad-s1)');
+  });
+});
+
+describe('TextLayer box border', () => {
+  it('draws a border rect on the position box', () => {
+    const layer: TextLayerType = {
+      id: 't1',
+      type: 'text',
+      position: { x: 0, y: 0, width: 400, height: 200 },
+      content: {
+        text: 'Hi',
+        style: {
+          fontSize: 40,
+          color: '#000',
+          borderColor: '#f00',
+          borderWidth: 3,
+          borderStyle: 'dotted',
+        },
+      },
+    };
+    const { container } = render(
+      <svg>
+        <TextLayer layer={layer} viewport={viewport} blockTime={0} />
+      </svg>,
+    );
+    const rect = container.querySelector('rect')!;
+    expect(rect).not.toBeNull();
+    expect(rect.getAttribute('stroke')).toBe('#f00');
+    expect(rect.getAttribute('stroke-width')).toBe('3');
+    expect(rect.getAttribute('width')).toBe('400');
+    expect(rect.getAttribute('height')).toBe('200');
+  });
+});

package/src/__tests__/transitionStyles.test.ts

@@ -0,0 +1,125 @@
+import { readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { describe, expect, it } from 'vitest';
+import type { TransitionDirection, TransitionType } from '@bendyline/squisq/schemas';
+import { TRANSITION_TYPES } from '@bendyline/squisq/schemas';
+import { getTransitionClass } from '../utils/animationUtils';
+
+const transitionCss = readFileSync(
+  resolve(process.cwd(), 'packages/react/src/styles/doc-animations.css'),
+  'utf8',
+);
+
+const directionalTypes: TransitionType[] = [
+  'cover',
+  'pan',
+  'pull',
+  'push',
+  'reveal',
+  'strips',
+  'uncover',
+  'wipe',
+];
+
+const axisTypes: TransitionType[] = ['blinds', 'comb', 'randomBar', 'randomBars', 'split'];
+const cardinalDirections = [
+  'left',
+  'right',
+  'up',
+  'down',
+] as const satisfies readonly TransitionDirection[];
+const axisDirections = ['horizontal', 'vertical'] as const satisfies readonly TransitionDirection[];
+
+function collectGeneratedTransitionClasses(): string[] {
+  const classNames = new Set<string>();
+
+  for (const type of TRANSITION_TYPES) {
+    if (type === 'cut') continue;
+    classNames.add(getTransitionClass(type, true));
+    classNames.add(getTransitionClass(type, false));
+  }
+
+  for (const type of directionalTypes) {
+    for (const direction of cardinalDirections) {
+      classNames.add(getTransitionClass(type, true, direction));
+      classNames.add(getTransitionClass(type, false, direction));
+    }
+  }
+
+  for (const type of axisTypes) {
+    for (const direction of axisDirections) {
+      classNames.add(getTransitionClass(type, true, direction));
+      classNames.add(getTransitionClass(type, false, direction));
+    }
+  }
+
+  return [...classNames].sort();
+}
+
+describe('transition CSS coverage', () => {
+  it('contains enter and exit selectors for every generated transition class', () => {
+    for (const className of collectGeneratedTransitionClasses()) {
+      expect(transitionCss, className).toContain(`.${className}`);
+    }
+  });
+});
+
+/** All `@keyframes <name>` defined in the stylesheet. */
+function definedKeyframes(): Set<string> {
+  const names = new Set<string>();
+  for (const m of transitionCss.matchAll(/@keyframes\s+([A-Za-z0-9_-]+)/g)) {
+    names.add(m[1]);
+  }
+  return names;
+}
+
+/**
+ * Map each `.transition-<x>-(enter|exit)` selector to the keyframe its rule
+ * animates. Parses top-level `selectors { body }` blocks and reads the first
+ * identifier of the `animation:` shorthand. Returns null for a transition rule
+ * with no `animation` property (itself a defect).
+ */
+function transitionRuleKeyframes(): Map<string, string | null> {
+  const map = new Map<string, string | null>();
+  const ruleRe = /([^{}]+)\{([^{}]*)\}/g;
+  let rule: RegExpExecArray | null;
+  while ((rule = ruleRe.exec(transitionCss)) !== null) {
+    const selectors = rule[1].split(',').map((s) => s.trim());
+    const transitionSelectors = selectors.filter((s) =>
+      /\.transition-[A-Za-z0-9-]+-(?:enter|exit)\b/.test(s),
+    );
+    if (transitionSelectors.length === 0) continue;
+    const animMatch = rule[2].match(/animation:\s*([A-Za-z0-9_-]+)/);
+    const keyframe = animMatch ? animMatch[1] : null;
+    for (const selector of transitionSelectors) {
+      const classMatch = selector.match(/\.(transition-[A-Za-z0-9-]+-(?:enter|exit))/);
+      if (classMatch && !map.has(classMatch[1])) map.set(classMatch[1], keyframe);
+    }
+  }
+  return map;
+}
+
+describe('transition keyframe integrity', () => {
+  it('every transition rule animates a defined @keyframes (catches typos)', () => {
+    const keyframes = definedKeyframes();
+    const broken: string[] = [];
+    for (const [selector, keyframe] of transitionRuleKeyframes()) {
+      if (keyframe === null) broken.push(`${selector}: no animation property`);
+      else if (!keyframes.has(keyframe)) broken.push(`${selector}: missing @keyframes ${keyframe}`);
+    }
+    expect(broken, broken.join('\n')).toEqual([]);
+  });
+
+  it('every generated transition class resolves to a defined keyframe', () => {
+    // Ties the function output to the CSS end-to-end: a class the player can
+    // emit must have a rule, and that rule must animate a real keyframe.
+    const keyframes = definedKeyframes();
+    const rules = transitionRuleKeyframes();
+    for (const className of collectGeneratedTransitionClasses()) {
+      const keyframe = rules.get(className);
+      expect(keyframe, `${className} has no transition rule`).toBeDefined();
+      expect(keyframe, `${className} animates undefined keyframe ${keyframe}`).not.toBeNull();
+      if (keyframe) expect(keyframes.has(keyframe), `${className} -> ${keyframe}`).toBe(true);
+    }
+  });
+});

package/src/__tests__/useDocPlayback.transition.test.ts

@@ -0,0 +1,70 @@
+/**
+ * useDocPlayback — block transition state is derived synchronously.
+ *
+ * Regression guard for the between-block "flash": a newly active block must
+ * report `isEntering` (and its outgoing `previousBlock`) on the SAME render it
+ * becomes current — not a frame later via an effect. Otherwise the block paints
+ * fully settled for a frame and then snaps back to the start of its entrance
+ * animation. The distinguishing assertion is `previousBlock` during the next
+ * block's entrance with NO timer/effect advanced (the old effect-based path
+ * only set it after a `setTimeout`).
+ */
+
+import { describe, it, expect } from 'vitest';
+import { renderHook } from '@testing-library/react';
+import { VIEWPORT_PRESETS } from '@bendyline/squisq/doc';
+import type { Doc, Block } from '@bendyline/squisq/schemas';
+import { useDocPlayback } from '../hooks/useDocPlayback';
+
+function block(id: string, startTime: number): Block {
+  return {
+    id,
+    startTime,
+    duration: 5,
+    audioSegment: 0,
+    transition: { type: 'fade', duration: 0.5 },
+    layers: [],
+  };
+}
+
+const doc: Doc = {
+  articleId: 'd',
+  duration: 10,
+  blocks: [block('a', 0), block('b', 5)],
+  audio: { segments: [] },
+};
+
+describe('useDocPlayback — synchronous block transitions', () => {
+  it('exposes the entering block + outgoing previousBlock on the same render (no effect flush)', () => {
+    const { result, rerender } = renderHook(
+      ({ t }: { t: number }) => useDocPlayback(doc, t, VIEWPORT_PRESETS.landscape),
+      { initialProps: { t: 0 } },
+    );
+
+    // Establish block A as the current block first.
+    expect(result.current.currentBlockIndex).toBe(0);
+
+    // Cross into block B's entrance window: it is entering AND crossfading from
+    // A immediately — the old code left previousBlock null until a setTimeout.
+    rerender({ t: 5.1 });
+    expect(result.current.currentBlockIndex).toBe(1);
+    expect(result.current.isEntering).toBe(true);
+    expect(result.current.isExiting).toBe(true);
+    expect(result.current.previousBlock?.id).toBe('a');
+
+    // Past the entrance window: settled, no crossfade.
+    rerender({ t: 7 });
+    expect(result.current.isEntering).toBe(false);
+    expect(result.current.isExiting).toBe(false);
+    expect(result.current.previousBlock).toBeNull();
+  });
+
+  it('isEntering is a pure function of blockTime vs the transition duration', () => {
+    const enteringAt = (t: number) =>
+      renderHook(() => useDocPlayback(doc, t, VIEWPORT_PRESETS.landscape)).result.current
+        .isEntering;
+    expect(enteringAt(5.0)).toBe(true); // blockTime 0.0 < 0.5
+    expect(enteringAt(5.4)).toBe(true); // blockTime 0.4 < 0.5
+    expect(enteringAt(5.6)).toBe(false); // blockTime 0.6 >= 0.5
+  });
+});

package/src/hooks/useAudioSync.ts

@@ -120,6 +120,13 @@ export function useAudioSync(
     if (!audio) return;
 
     const handleTimeUpdate = () => {
+      // In fallback mode the <audio> element is NOT the clock — there's no real
+      // source (e.g. the editor preview's synthetic, empty-src track), so the
+      // synthetic timer and `seekTo` own `currentTime`. A `timeupdate` fired as
+      // a side effect of programmatically setting `audio.currentTime` (during a
+      // seek) would otherwise clobber the just-seeked position with the empty
+      // element's unreliable `currentTime`, snapping the scrubber back.
+      if (fallbackMode.current) return;
       // Calculate overall timeline position
       const segmentStart = segmentStarts.current[currentSegment] || 0;
       const overallTime = segmentStart + audio.currentTime;
@@ -127,7 +134,13 @@ export function useAudioSync(
     };
 
     const handlePlay = () => {
-      fallbackMode.current = false;
+      // Don't clear `fallbackMode` here. Whether the <audio> element is really
+      // the clock is decided authoritatively by the play() promise: it only
+      // resolves (clearing fallback, see `play`) when a real source actually
+      // plays. The 'play' event, by contrast, can fire spuriously on the
+      // source-less preview element — and clearing fallback there makes the
+      // synthetic timer's tick guard bail on its next frame, freezing the
+      // clock and the scrubber after a seek/resume.
       setIsPlaying(true);
     };
     const handlePause = () => setIsPlaying(false);