@bendyline/squisq-react 1.4.2 → 2.0.0

package/src/__tests__/LinearDocView.test.tsx

@@ -1,5 +1,5 @@
 import { describe, it, expect, vi } from 'vitest';
-import { render } from '@testing-library/react';
+import { fireEvent, render } from '@testing-library/react';
 import { LinearDocView } from '../LinearDocView';
 import type { Doc, Block } from '@bendyline/squisq/schemas';
 import { DARK_SURFACE, DEFAULT_THEME, LIGHT_SURFACE } from '@bendyline/squisq/schemas';
@@ -58,6 +58,20 @@ describe('LinearDocView', () => {
     expect((el as HTMLElement).style.overflowY).toBe('auto');
   });
 
+  it('globally scrolls with up and down arrows when enabled', () => {
+    const doc = mkDoc([mkBlock({ contents: [paragraph(text('Scrollable body'))] })]);
+    const { container } = render(<LinearDocView doc={doc} globalKeyboardShortcuts />);
+    const scroller = container.querySelector<HTMLElement>('.squisq-linear')!;
+    const scrollBy = vi.fn();
+    Object.defineProperty(scroller, 'scrollBy', { configurable: true, value: scrollBy });
+
+    fireEvent.keyDown(document, { key: 'ArrowDown' });
+    fireEvent.keyDown(document, { key: 'ArrowUp' });
+
+    expect(scrollBy).toHaveBeenNthCalledWith(1, { top: 64, behavior: 'smooth' });
+    expect(scrollBy).toHaveBeenNthCalledWith(2, { top: -64, behavior: 'smooth' });
+  });
+
   it('renders preamble content (no heading)', () => {
     const doc = mkDoc([
       mkBlock({
@@ -176,6 +190,24 @@ describe('LinearDocView', () => {
     expect(svg).toBeTruthy();
   });
 
+  it('renders transform-generated template blocks without authoring nodes', () => {
+    const doc = mkDoc([
+      mkBlock({
+        id: 'transform-stat',
+        template: 'statHighlight',
+        stat: '42%',
+        description: 'Year-over-year growth',
+      } as Partial<Block>),
+    ]);
+
+    const { container } = render(<LinearDocView doc={doc} />);
+    const section = container.querySelector('[data-block-id="transform-stat"]');
+    expect(section?.getAttribute('data-template')).toBe('statHighlight');
+    expect(section?.querySelector('.squisq-linear-card svg')).toBeTruthy();
+    expect(section?.textContent).toContain('42%');
+    expect(section?.textContent).toContain('Year-over-year growth');
+  });
+
   it('renders children recursively', () => {
     const doc = mkDoc([
       mkBlock({
@@ -198,6 +230,22 @@ describe('LinearDocView', () => {
     expect(container.textContent).toContain('Child body');
   });
 
+  it('assigns unique pre-order indices across nested and top-level blocks', () => {
+    const doc = mkDoc([
+      mkBlock({
+        id: 'parent',
+        children: [mkBlock({ id: 'child' })],
+      }),
+      mkBlock({ id: 'sibling' }),
+    ]);
+    const { container } = render(<LinearDocView doc={doc} />);
+    expect(
+      Array.from(container.querySelectorAll('.squisq-linear-section')).map((node) =>
+        node.getAttribute('data-block-index'),
+      ),
+    ).toEqual(['0', '1', '2']);
+  });
+
   it('renders multiple top-level blocks', () => {
     const doc = mkDoc([
       mkBlock({
@@ -301,7 +349,7 @@ describe('LinearDocView markdown prop', () => {
 });
 
 describe('LinearDocView unknown template annotations', () => {
-  it('warns once per unknown template name and falls back to plain markdown', () => {
+  it('renders the canonical visible fallback without hidden console output', () => {
     const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
     const doc = mkDoc([
       mkBlock({
@@ -317,17 +365,49 @@ describe('LinearDocView unknown template annotations', () => {
     ]);
 
     const { container } = render(<LinearDocView doc={doc} />);
-    // Renders as plain markdown: heading + body, no SVG card.
     expect(container.textContent).toContain('Mystery Section');
     expect(container.textContent).toContain('Fallback body content');
-    expect(container.querySelector('.squisq-linear-card')).toBeNull();
-
-    // Re-render: the warning stays one-shot per unknown template name.
-    render(<LinearDocView doc={doc} />);
-    const sentinelCalls = warnSpy.mock.calls.filter((c) =>
-      String(c[0]).includes('no-such-template-xyz'),
-    );
-    expect(sentinelCalls.length).toBe(1);
+    expect(container.textContent).toContain('Unknown template "no-such-template-xyz"');
+    expect(container.querySelector('.squisq-linear-card')).not.toBeNull();
+    expect(warnSpy).not.toHaveBeenCalled();
     warnSpy.mockRestore();
   });
 });
+
+describe('LinearDocView custom template materialization', () => {
+  it('renders document-scoped templates through the canonical API', () => {
+    const doc: Doc = {
+      ...mkDoc([
+        mkBlock({
+          id: 'custom-1',
+          sourceHeading: {
+            type: 'heading',
+            depth: 2,
+            children: [text('Custom Hero')],
+            templateAnnotation: { template: 'hero' },
+          },
+          contents: [paragraph(text('Custom body'))],
+        }),
+      ]),
+      customTemplates: [
+        {
+          name: 'hero',
+          label: 'Hero',
+          viewport: { width: 1920, height: 1080 },
+          layers: [
+            {
+              id: 'hero-title',
+              type: 'text',
+              position: { x: '5%', y: '10%', width: '90%' },
+              content: { text: '{title}: {content}', style: { fontSize: 48, color: '#000000' } },
+            },
+          ],
+        },
+      ],
+    };
+
+    const { container } = render(<LinearDocView doc={doc} />);
+    expect(container.textContent).toContain('Custom Hero: Custom body');
+    expect(container.textContent).not.toContain('Unknown template');
+  });
+});

package/src/__tests__/MapLayer.test.tsx

@@ -0,0 +1,63 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+import { render, waitFor } from '@testing-library/react';
+import type { MapLayer as MapLayerSchema } from '@bendyline/squisq/schemas';
+
+const { composeMapImage } = vi.hoisted(() => ({
+  composeMapImage: vi.fn(async () => 'data:image/png;base64,map'),
+}));
+vi.mock('../utils/mapTileUtils', () => ({ composeMapImage }));
+
+import { MapLayer } from '../layers/MapLayer';
+
+function layer(
+  markers: MapLayerSchema['content']['markers'],
+  showAttribution = true,
+): MapLayerSchema {
+  return {
+    id: 'map',
+    type: 'map',
+    position: { x: 0, y: 0, width: 100, height: 100 },
+    content: {
+      center: { lat: 1, lng: 2 },
+      zoom: 4,
+      style: 'road',
+      markers,
+      showAttribution,
+    },
+  };
+}
+
+describe('MapLayer dependencies', () => {
+  beforeEach(() => composeMapImage.mockClear());
+
+  it('recomposes when markers or attribution change', async () => {
+    const firstMarkers = [{ lat: 1, lng: 2, label: 'A' }];
+    const { rerender } = render(
+      <svg>
+        <MapLayer
+          layer={layer(firstMarkers)}
+          basePath="."
+          viewport={{ width: 100, height: 100 }}
+          blockTime={0}
+        />
+      </svg>,
+    );
+    await waitFor(() => expect(composeMapImage).toHaveBeenCalledTimes(1));
+
+    const secondMarkers = [{ lat: 3, lng: 4, label: 'B' }];
+    rerender(
+      <svg>
+        <MapLayer
+          layer={layer(secondMarkers, false)}
+          basePath="."
+          viewport={{ width: 100, height: 100 }}
+          blockTime={0}
+        />
+      </svg>,
+    );
+    await waitFor(() => expect(composeMapImage).toHaveBeenCalledTimes(2));
+    expect(composeMapImage).toHaveBeenLastCalledWith(
+      expect.objectContaining({ markers: secondMarkers, showAttribution: false }),
+    );
+  });
+});

package/src/__tests__/MarkdownRenderer.test.tsx

@@ -289,7 +289,7 @@ describe('MarkdownRenderer', () => {
     expect(container.querySelector('span')).toBeNull();
   });
 
-  it('preserves raw HTML only with the trusted opt-in', () => {
+  it('preserves trusted HTML structure without executable attributes', () => {
     const { container } = render(
       <MarkdownRenderer
         nodes={parseNodes('<div><span class="trusted" onclick="alert(1)">ok</span></div>')}
@@ -297,7 +297,18 @@ describe('MarkdownRenderer', () => {
       />,
     );
     const span = container.querySelector('span.trusted');
-    expect(span?.getAttribute('onclick')).toBe('alert(1)');
+    expect(span?.getAttribute('onclick')).toBeNull();
+  });
+
+  it('blocks executable URLs under the trusted policy', () => {
+    const { container } = render(
+      <MarkdownRenderer
+        nodes={parseNodes('<a href="javascript:alert(1)">bad</a><img src="javascript:x">')}
+        htmlPolicy="trusted"
+      />,
+    );
+    expect(container.querySelector('a')?.getAttribute('href')).toBeNull();
+    expect(container.querySelector('img')?.getAttribute('src')).toBeNull();
   });
 
   // Host-affecting tags (style/script/…) must never reach the document.

package/src/__tests__/MediaClipLayer.test.tsx

@@ -0,0 +1,70 @@
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { act, render, waitFor } from '@testing-library/react';
+import type { MediaProvider, ScheduledClip } from '@bendyline/squisq/schemas';
+import { MediaClipLayer } from '../MediaClipLayer';
+import { MediaContext } from '../hooks/MediaContext';
+
+afterEach(() => vi.restoreAllMocks());
+
+describe('MediaClipLayer', () => {
+  it('mutes scheduled audio when the player muted contract is enabled', () => {
+    vi.spyOn(window.HTMLMediaElement.prototype, 'pause').mockImplementation(() => {});
+    const clip: ScheduledClip = {
+      id: 'narration',
+      kind: 'audio',
+      src: 'narration.mp3',
+      absoluteStart: 0,
+      absoluteEnd: 5,
+      sourceIn: 0,
+      anchor: 'document',
+    };
+    const { container } = render(
+      <MediaClipLayer schedule={[clip]} currentTime={0} isPlaying={false} basePath="." muted />,
+    );
+    expect(container.querySelector('audio')?.muted).toBe(true);
+  });
+
+  it('restores a paused clip position after an async media URL resolves', async () => {
+    vi.spyOn(window.HTMLMediaElement.prototype, 'pause').mockImplementation(() => {});
+    let resolveUrl!: (url: string) => void;
+    const provider = {
+      resolveUrl: vi.fn(
+        () =>
+          new Promise<string>((resolve) => {
+            resolveUrl = resolve;
+          }),
+      ),
+    } as unknown as MediaProvider;
+    const clip: ScheduledClip = {
+      id: 'background-video',
+      kind: 'video',
+      src: 'background.mp4',
+      absoluteStart: 0,
+      absoluteEnd: 10,
+      sourceIn: 2,
+      anchor: 'document',
+    };
+
+    const { container } = render(
+      <MediaContext.Provider value={provider}>
+        <MediaClipLayer
+          schedule={[clip]}
+          currentTime={5}
+          isPlaying={false}
+          basePath="/media"
+          muted
+        />
+      </MediaContext.Provider>,
+    );
+    const video = container.querySelector('video')!;
+    await waitFor(() => expect(video.currentTime).toBe(7));
+
+    // Replacing an HTMLMediaElement source resets its playback position in a
+    // browser. Simulate that reset before the provider's blob URL arrives.
+    video.currentTime = 0;
+    await act(async () => resolveUrl('blob:resolved-background'));
+
+    await waitFor(() => expect(video.getAttribute('src')).toBe('blob:resolved-background'));
+    expect(video.currentTime).toBe(7);
+  });
+});

package/src/__tests__/MediaContext.test.tsx

@@ -0,0 +1,51 @@
+import { act, render, screen } from '@testing-library/react';
+import { describe, expect, it, vi } from 'vitest';
+import type { MediaProvider } from '@bendyline/squisq/schemas';
+import { MediaContext, useMediaUrl } from '../hooks/MediaContext';
+
+function deferred<T>() {
+  let resolve!: (value: T) => void;
+  let reject!: (reason?: unknown) => void;
+  const promise = new Promise<T>((res, rej) => {
+    resolve = res;
+    reject = rej;
+  });
+  return { promise, resolve, reject };
+}
+
+function Probe({ path }: { path: string }) {
+  return <span data-testid="url">{useMediaUrl(path, '.')}</span>;
+}
+
+describe('useMediaUrl', () => {
+  it('clears a stale URL and consumes provider rejection', async () => {
+    const first = deferred<string>();
+    const second = deferred<string>();
+    const resolveUrl = vi
+      .fn()
+      .mockReturnValueOnce(first.promise)
+      .mockReturnValueOnce(second.promise);
+    const provider = { resolveUrl } as unknown as MediaProvider;
+    const { rerender } = render(
+      <MediaContext.Provider value={provider}>
+        <Probe path="first.png" />
+      </MediaContext.Provider>,
+    );
+    expect(screen.getByTestId('url').textContent).toBe('./first.png');
+
+    rerender(
+      <MediaContext.Provider value={provider}>
+        <Probe path="second.png" />
+      </MediaContext.Provider>,
+    );
+    expect(screen.getByTestId('url').textContent).toBe('./second.png');
+
+    await act(async () => {
+      first.resolve('blob:first');
+      await first.promise;
+      second.reject(new Error('missing'));
+      await second.promise.catch(() => undefined);
+    });
+    expect(screen.getByTestId('url').textContent).toBe('./second.png');
+  });
+});

package/src/__tests__/PathLayer.test.tsx

@@ -11,7 +11,7 @@ function renderPath(layer: PathLayerType) {
       <PathLayer layer={layer} viewport={viewport} blockTime={0} />
     </svg>,
   );
-  return container.querySelector('path')!;
+  return container.querySelector('.block-layer--path > path')!;
 }
 
 describe('PathLayer', () => {
@@ -70,4 +70,15 @@ describe('PathLayer', () => {
     });
     expect(path.getAttribute('d')).toBe('M 1 2 L 3 4');
   });
+
+  it('reads the old serialized arrow field without exposing it in the PathLayer type', () => {
+    const legacyLayer = {
+      id: 'legacy-arrow',
+      type: 'path',
+      position: { x: 0, y: 0, width: 100, height: 100 },
+      content: { d: 'M 0 0 L 100 100', arrow: 'end' },
+    } as unknown as PathLayerType;
+
+    expect(renderPath(legacyLayer).getAttribute('marker-end')).toMatch(/^url\(#marker-end-/);
+  });
 });

package/src/__tests__/VideoLayer.test.tsx

@@ -0,0 +1,94 @@
+/** @vitest-environment jsdom */
+
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { cleanup, render, waitFor } from '@testing-library/react';
+import type { VideoLayer as VideoLayerType } from '@bendyline/squisq/schemas';
+import { VideoLayer } from '../layers/VideoLayer';
+
+const layer: VideoLayerType = {
+  id: 'video',
+  type: 'video',
+  position: { x: 0, y: 0, width: 640, height: 360 },
+  content: {
+    src: 'clip.mp4',
+    alt: 'Demo clip',
+    clipStart: 2,
+    clipEnd: 8,
+    startAt: 1,
+  },
+};
+
+beforeEach(() => {
+  vi.spyOn(HTMLMediaElement.prototype, 'play').mockResolvedValue(undefined);
+  vi.spyOn(HTMLMediaElement.prototype, 'pause').mockImplementation(() => undefined);
+});
+
+afterEach(() => {
+  cleanup();
+  vi.restoreAllMocks();
+});
+
+describe('VideoLayer playback synchronization', () => {
+  it('joins the document clock when mounted partway through a block', async () => {
+    const { container, rerender } = render(
+      <svg>
+        <VideoLayer
+          layer={layer}
+          basePath="/media"
+          viewport={{ width: 640, height: 360 }}
+          blockTime={4}
+          isPlaying
+        />
+      </svg>,
+    );
+    const video = container.querySelector('video')!;
+
+    // clipStart 2 + (blockTime 4 - startAt 1) = source time 5.
+    await waitFor(() => expect(video.currentTime).toBe(5));
+
+    rerender(
+      <svg>
+        <VideoLayer
+          layer={layer}
+          basePath="/media"
+          viewport={{ width: 640, height: 360 }}
+          blockTime={6}
+          isPlaying
+        />
+      </svg>,
+    );
+    expect(video.currentTime).toBe(7);
+
+    rerender(
+      <svg>
+        <VideoLayer
+          layer={layer}
+          basePath="/media"
+          viewport={{ width: 640, height: 360 }}
+          blockTime={20}
+          isPlaying
+        />
+      </svg>,
+    );
+    expect(video.currentTime).toBe(8);
+    expect(video.pause).toHaveBeenCalled();
+  });
+
+  it('holds at the in-point until startAt', async () => {
+    const { container } = render(
+      <svg>
+        <VideoLayer
+          layer={layer}
+          basePath="/media"
+          viewport={{ width: 640, height: 360 }}
+          blockTime={0.5}
+          isPlaying
+        />
+      </svg>,
+    );
+    const video = container.querySelector('video')!;
+
+    await waitFor(() => expect(video.currentTime).toBe(2));
+    expect(video.pause).toHaveBeenCalled();
+  });
+});

package/src/__tests__/fillStyle.test.tsx

@@ -75,8 +75,9 @@ describe('ShapeLayer fill/border', () => {
         />
       </svg>,
     );
-    expect(container.querySelector('linearGradient')).not.toBeNull();
-    expect(container.querySelector('rect')!.getAttribute('fill')).toBe('url(#squisq-grad-s1)');
+    const gradient = container.querySelector('linearGradient');
+    expect(gradient).not.toBeNull();
+    expect(container.querySelector('rect')!.getAttribute('fill')).toBe(`url(#${gradient!.id})`);
   });
 });
 

package/src/__tests__/standaloneEntry.test.tsx

@@ -0,0 +1,103 @@
+import { afterEach, describe, expect, it } from 'vitest';
+import type { Doc } from '@bendyline/squisq/schemas';
+import { getHandle, mount, unmount } from '../standalone-entry';
+import * as standalone from '../standalone-entry';
+
+function doc(id: string): Doc {
+  return {
+    articleId: id,
+    duration: 2,
+    blocks: [{ id: `${id}-block`, startTime: 0, duration: 2, audioSegment: 0, layers: [] }],
+    audio: { segments: [] },
+  };
+}
+
+function animatedDoc(id: string): Doc {
+  const result = doc(id);
+  result.blocks[0].layers = [
+    {
+      type: 'text',
+      id: `${id}-title`,
+      content: { text: 'Standalone motion', style: { fontSize: 48, color: '#fff' } },
+      position: { x: 100, y: 100 },
+      animation: { type: 'fadeIn', duration: 1 },
+    },
+  ];
+  return result;
+}
+
+const mountedElements: Element[] = [];
+
+afterEach(() => {
+  for (const element of mountedElements.splice(0)) unmount(element);
+});
+
+describe('standalone player instance handles', () => {
+  it('does not expose the removed mountStatic compatibility alias', () => {
+    expect('mountStatic' in standalone).toBe(false);
+  });
+
+  it('returns the render API for exactly the mounted player instance', async () => {
+    const firstRoot = document.createElement('div');
+    const secondRoot = document.createElement('div');
+    document.body.append(firstRoot, secondRoot);
+    mountedElements.push(firstRoot, secondRoot);
+
+    const first = mount(firstRoot, doc('first'), { renderMode: true });
+    const second = mount(secondRoot, doc('second'), { renderMode: true });
+    const [firstAPI, secondAPI] = await Promise.all([first.renderAPI, second.renderAPI]);
+
+    expect(firstAPI?.getBlocks()[0].id).toBe('first-block');
+    expect(secondAPI?.getBlocks()[0].id).toBe('second-block');
+    expect(getHandle(firstRoot)).toBe(first);
+    expect(getHandle(secondRoot)).toBe(second);
+    expect('seekTo' in window).toBe(false);
+    expect('getDuration' in window).toBe(false);
+    expect('squisqActivePlayerId' in window).toBe(false);
+    expect('squisqPlayers' in window).toBe(false);
+  });
+
+  it('resolves a null render API outside render mode and owns unmounting', async () => {
+    const root = document.createElement('div');
+    document.body.append(root);
+    mountedElements.push(root);
+
+    const handle = mount(root, doc('static'), { mode: 'static' });
+    expect(await handle.renderAPI).toBeNull();
+    expect(getHandle(root)).toBe(handle);
+
+    handle.unmount();
+    expect(getHandle(root)).toBeUndefined();
+  });
+
+  it('prevents a stale handle from unmounting a newer player in the same element', async () => {
+    const root = document.createElement('div');
+    document.body.append(root);
+    mountedElements.push(root);
+
+    const first = mount(root, doc('first'), { renderMode: true });
+    expect((await first.renderAPI)?.getBlocks()[0].id).toBe('first-block');
+
+    const second = mount(root, doc('second'), { renderMode: true });
+    expect((await second.renderAPI)?.getBlocks()[0].id).toBe('second-block');
+    expect(first.getRenderAPI()).toBeNull();
+
+    first.unmount();
+    expect(getHandle(root)).toBe(second);
+    expect(second.getRenderAPI()?.getBlocks()[0].id).toBe('second-block');
+  });
+
+  it('forwards the animationsEnabled render policy to the mounted player', async () => {
+    const root = document.createElement('div');
+    document.body.append(root);
+    mountedElements.push(root);
+
+    const handle = mount(root, animatedDoc('motionless'), {
+      renderMode: true,
+      animationsEnabled: false,
+    });
+    await handle.renderAPI;
+
+    expect(root.querySelector('[class*="anim-"]')).toBeNull();
+  });
+});

package/src/__tests__/useAudioSync.test.ts

@@ -0,0 +1,49 @@
+import { act, renderHook, waitFor } from '@testing-library/react';
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import type { AudioTrack } from '@bendyline/squisq/schemas';
+import { useAudioSync } from '../hooks/useAudioSync';
+
+const track: AudioTrack = {
+  segments: [{ src: 'https://cdn.example.test/a.mp3', name: 'a', duration: 2, startTime: 0 }],
+};
+
+afterEach(() => vi.restoreAllMocks());
+
+describe('useAudioSync resource loading', () => {
+  it('does not prefix absolute URLs and revokes a blob that resolves after cleanup', async () => {
+    let resolveFetch!: (value: unknown) => void;
+    const fetchPromise = new Promise((resolve) => {
+      resolveFetch = resolve;
+    });
+    const fetchSpy = vi
+      .spyOn(globalThis, 'fetch')
+      .mockReturnValue(fetchPromise as Promise<Response>);
+    const create = vi.spyOn(URL, 'createObjectURL').mockReturnValue('blob:late');
+    const revoke = vi.spyOn(URL, 'revokeObjectURL').mockImplementation(() => {});
+    const audioRef = { current: null };
+    const { unmount } = renderHook(() => useAudioSync(audioRef, track, '.'));
+
+    await waitFor(() => expect(fetchSpy).toHaveBeenCalled());
+    expect(fetchSpy.mock.calls[0][0]).toBe('https://cdn.example.test/a.mp3');
+    unmount();
+
+    await act(async () => {
+      resolveFetch({ ok: true, blob: async () => new Blob(['audio']) });
+      await fetchPromise;
+      await Promise.resolve();
+      await Promise.resolve();
+    });
+    expect(create).toHaveBeenCalled();
+    expect(revoke).toHaveBeenCalledWith('blob:late');
+  });
+
+  it('does not preload when an external controller disables the hook', async () => {
+    const fetchSpy = vi.spyOn(globalThis, 'fetch').mockResolvedValue({
+      ok: true,
+      blob: async () => new Blob(['audio']),
+    } as Response);
+    renderHook(() => useAudioSync({ current: null }, track, '.', false));
+    await act(async () => Promise.resolve());
+    expect(fetchSpy).not.toHaveBeenCalled();
+  });
+});