@bendyline/squisq-editor-react 1.5.3 → 1.6.1

package/src/__tests__/headingTransition.test.ts

@@ -0,0 +1,138 @@
+import { describe, it, expect } from 'vitest';
+import {
+  readHeadingLineTransition,
+  setHeadingLineTransition,
+  readBlockAttrsTransition,
+  setBlockAttrsTransition,
+  EMPTY_TRANSITION,
+} from '../headingTransition';
+
+describe('readHeadingLineTransition', () => {
+  it('returns empty for a plain heading', () => {
+    expect(readHeadingLineTransition('## Tips')).toEqual(EMPTY_TRANSITION);
+  });
+
+  it('returns empty for a non-heading line', () => {
+    expect(readHeadingLineTransition('Just a paragraph')).toEqual(EMPTY_TRANSITION);
+  });
+
+  it('reads transition from a Pandoc block', () => {
+    expect(readHeadingLineTransition('## Tips {transition=fade}')).toEqual({
+      type: 'fade',
+      direction: '',
+      duration: '',
+    });
+  });
+
+  it('reads type, direction and duration together', () => {
+    expect(
+      readHeadingLineTransition(
+        '## Tips {transition=push transitionDirection=left transitionDuration=0.7}',
+      ),
+    ).toEqual({ type: 'push', direction: 'left', duration: '0.7' });
+  });
+
+  it('reads a hand-typed transition from the {[…]} template params', () => {
+    expect(readHeadingLineTransition('## Tips {[title transition=zoom]}')).toEqual({
+      type: 'zoom',
+      direction: '',
+      duration: '',
+    });
+  });
+
+  it('prefers the Pandoc block over the template params when both set it', () => {
+    expect(
+      readHeadingLineTransition('## Tips {transition=fade} {[title transition=zoom]}'),
+    ).toEqual({ type: 'fade', direction: '', duration: '' });
+  });
+});
+
+describe('setHeadingLineTransition', () => {
+  it('adds a Pandoc block to a plain heading', () => {
+    expect(setHeadingLineTransition('## Tips', { type: 'fade', direction: '', duration: '' })).toBe(
+      '## Tips {transition=fade}',
+    );
+  });
+
+  it('writes the Pandoc block before an existing {[…]} template annotation', () => {
+    expect(
+      setHeadingLineTransition('## Tips {[title]}', { type: 'fade', direction: '', duration: '' }),
+    ).toBe('## Tips {transition=fade} {[title]}');
+  });
+
+  it('includes direction and duration when present', () => {
+    expect(
+      setHeadingLineTransition('## Tips', { type: 'push', direction: 'up', duration: '1.2' }),
+    ).toBe('## Tips {transition=push transitionDirection=up transitionDuration=1.2}');
+  });
+
+  it('updates an existing transition in place, preserving other params and the id', () => {
+    expect(
+      setHeadingLineTransition('## Tips {#intro transition=fade x=10}', {
+        type: 'zoom',
+        direction: '',
+        duration: '',
+      }),
+    ).toBe('## Tips {#intro x=10 transition=zoom}');
+  });
+
+  it('removes the transition (and an empty block) when set to none', () => {
+    expect(setHeadingLineTransition('## Tips {transition=fade}', EMPTY_TRANSITION)).toBe('## Tips');
+  });
+
+  it('keeps a non-empty Pandoc block when only the transition is cleared', () => {
+    expect(setHeadingLineTransition('## Tips {#intro transition=fade}', EMPTY_TRANSITION)).toBe(
+      '## Tips {#intro}',
+    );
+  });
+
+  it('drops direction/duration when the type is cleared', () => {
+    expect(
+      setHeadingLineTransition(
+        '## Tips {transition=push transitionDirection=left}',
+        EMPTY_TRANSITION,
+      ),
+    ).toBe('## Tips');
+  });
+
+  it('round-trips through read', () => {
+    const next = { type: 'wipe', direction: 'right', duration: '0.5' };
+    const line = setHeadingLineTransition('## Tips {[title]}', next);
+    expect(readHeadingLineTransition(line)).toEqual(next);
+  });
+
+  it('leaves non-heading lines untouched', () => {
+    expect(
+      setHeadingLineTransition('paragraph', { type: 'fade', direction: '', duration: '' }),
+    ).toBe('paragraph');
+  });
+});
+
+describe('block-attrs (WYSIWYG) helpers', () => {
+  it('reads from the dataBlockAttrs inner', () => {
+    expect(readBlockAttrsTransition('#intro transition=fade', null)).toEqual({
+      type: 'fade',
+      direction: '',
+      duration: '',
+    });
+  });
+
+  it('reads a hand-typed transition from dataTemplateParams', () => {
+    expect(readBlockAttrsTransition(null, 'transition=zoom x=1')).toEqual({
+      type: 'zoom',
+      direction: '',
+      duration: '',
+    });
+  });
+
+  it('writes a fresh inner when none exists', () => {
+    expect(setBlockAttrsTransition(null, { type: 'fade', direction: '', duration: '' })).toBe(
+      'transition=fade',
+    );
+  });
+
+  it('preserves the id and clears to null when emptied', () => {
+    expect(setBlockAttrsTransition('transition=fade', EMPTY_TRANSITION)).toBeNull();
+    expect(setBlockAttrsTransition('#intro transition=fade', EMPTY_TRANSITION)).toBe('#intro');
+  });
+});

package/src/__tests__/layoutChildRoundTrip.test.ts

@@ -0,0 +1,71 @@
+/**
+ * Layout child sub-blocks round-trip through the markdown ↔ Tiptap bridge.
+ *
+ * Layouts now persist each layer as a readable `### {#id} {[type …]}` child
+ * heading (no base64 `layers=` blob); a text layer's content is the child's
+ * markdown body. These tests pin that serialization seam — the same
+ * `data-template` / `data-template-params` / `data-block-attrs` attributes the
+ * LayoutAdapter reads back — without standing up a full editor.
+ */
+
+import { describe, it, expect } from 'vitest';
+import { markdownToTiptap, tiptapToMarkdown } from '../tiptapBridge';
+
+// Parent title "Pricing" (not "Layout") avoids the bridge's template-label
+// de-dup heuristic, which would strip a title equal to the template's label.
+const LAYOUT = [
+  '## Pricing {[layout]}',
+  '',
+  '### {#text-1} {[text x=360 y=380 width=1200 height=320 align=center]}',
+  '',
+  'Welcome to the **bold** layout',
+  '',
+  '- first point',
+  '- second point',
+  '',
+  '### {#box-1} {[rectangle x=760 y=390 width=400 height=300 fill="#e0e7ff"]}',
+  '',
+  '### {#pic-1} {[image x=40 y=40 width=320 height=240 src=cover.png alt="Cover"]}',
+].join('\n');
+
+describe('Layout child sub-block round-trip', () => {
+  it('extracts a text layer annotation into the template + block-attr attributes', () => {
+    const html = markdownToTiptap('### {#text-1} {[text x=360 y=380 width=1200 height=320]}');
+    expect(html).toContain('data-template="text"');
+    expect(html).toContain('data-template-params="x=360 y=380 width=1200 height=320"');
+    expect(html).toContain('data-block-attrs="#text-1"');
+    expect(html).not.toContain('{[text'); // raw annotation text stripped
+  });
+
+  it('keeps a text layer body (marks + list) as sibling blocks, not in the heading', () => {
+    const html = markdownToTiptap(
+      ['### {#text-1} {[text x=0 y=0]}', '', 'Hello **world**', '', '- a', '- b'].join('\n'),
+    );
+    // Heading is empty; the body is its own paragraph + list.
+    expect(html).toContain('<strong>world</strong>');
+    expect(html).toContain('<ul>');
+    expect(html).toContain('<li>');
+  });
+
+  it('round-trips a full layout (text + box + image) losslessly and idempotently', () => {
+    const back = tiptapToMarkdown(markdownToTiptap(LAYOUT));
+    expect(back).toContain('## Pricing {[layout]}');
+    // Child sub-blocks keep their id + annotation (empty-text headings get an
+    // extra space after `###`, which re-parses identically — assert spacing-free).
+    expect(back).toContain('{#text-1} {[text x=360 y=380 width=1200 height=320 align=center]}');
+    expect(back).toContain(
+      '{#box-1} {[rectangle x=760 y=390 width=400 height=300 fill="#e0e7ff"]}',
+    );
+    expect(back).toContain(
+      '{#pic-1} {[image x=40 y=40 width=320 height=240 src=cover.png alt="Cover"]}',
+    );
+    // The text layer's body markdown survives as readable content.
+    expect(back).toContain('Welcome to the **bold** layout');
+    expect(back).toContain('- first point');
+    expect(back).toContain('- second point');
+    // No base64 layers blob anywhere — the whole point of the change.
+    expect(back).not.toContain('layers=');
+    // Stable: a second pass reproduces the first exactly.
+    expect(tiptapToMarkdown(markdownToTiptap(back))).toBe(back);
+  });
+});

package/src/__tests__/plainHtmlPreview.test.tsx

@@ -10,10 +10,10 @@ function getIframeSrcDoc(): string {
 }
 
 describe('PlainHtmlPreview', () => {
-  it('renders the markdown into the iframe srcDoc', () => {
+  it('renders the markdown into the iframe srcDoc', async () => {
     render(<PlainHtmlPreview markdown={'# Hello\n\nWorld'} />);
+    await waitFor(() => expect(getIframeSrcDoc()).toContain('<!DOCTYPE html>'));
     const srcdoc = getIframeSrcDoc();
-    expect(srcdoc).toContain('<!DOCTYPE html>');
     expect(srcdoc).toContain('<h1>Hello</h1>');
     expect(srcdoc).toContain('<p>World</p>');
   });
@@ -26,14 +26,14 @@ describe('PlainHtmlPreview', () => {
     expect(sandbox).not.toContain('allow-scripts');
   });
 
-  it('applies pre-resolved images via the images prop', () => {
+  it('applies pre-resolved images via the images prop', async () => {
     render(
       <PlainHtmlPreview
         markdown={'![a](a.jpg)'}
         images={new Map([['a.jpg', 'data:image/png;base64,AAA']])}
       />,
     );
-    expect(getIframeSrcDoc()).toContain('src="data:image/png;base64,AAA"');
+    await waitFor(() => expect(getIframeSrcDoc()).toContain('src="data:image/png;base64,AAA"'));
   });
 
   it('resolves image URLs through the supplied mediaProvider', async () => {
@@ -68,19 +68,21 @@ describe('PlainHtmlPreview', () => {
     expect(provider.resolveUrl).not.toHaveBeenCalled();
   });
 
-  it('applies the supplied theme to the iframe document', () => {
+  it('applies the supplied theme to the iframe document', async () => {
     const theme = resolveTheme('warm-earth');
     render(<PlainHtmlPreview markdown={'# Hi'} theme={theme} />);
+    await waitFor(() =>
+      expect(getIframeSrcDoc()).toContain(`--plain-bg: ${theme.colors.background};`),
+    );
     const srcdoc = getIframeSrcDoc();
-    expect(srcdoc).toContain(`--plain-bg: ${theme.colors.background};`);
     expect(srcdoc).toContain(`--plain-primary: ${theme.colors.primary};`);
     expect(srcdoc).toContain('--plain-body-font:');
   });
 
-  it('loads Google Fonts for themes that reference google-hosted faces', () => {
+  it('loads Google Fonts for themes that reference google-hosted faces', async () => {
     const theme = resolveTheme('documentary');
     render(<PlainHtmlPreview markdown={'# Hi'} theme={theme} />);
-    expect(getIframeSrcDoc()).toContain('https://fonts.googleapis.com/css2?');
+    await waitFor(() => expect(getIframeSrcDoc()).toContain('https://fonts.googleapis.com/css2?'));
   });
 
   it('resolves raw HTML <img> tags too (resized image case)', async () => {

package/src/__tests__/previewControls.test.tsx

@@ -0,0 +1,70 @@
+/**
+ * @vitest-environment jsdom
+ */
+import { afterEach, describe, expect, it } from 'vitest';
+import { cleanup, fireEvent, render, screen, waitFor } from '@testing-library/react';
+import { EditorProvider, useEditorContext } from '../EditorContext';
+import { PreviewModeSwitch, PreviewSettingsProvider, usePreviewSettings } from '../PreviewControls';
+
+function ModeProbe() {
+  const { activeDisplayMode } = usePreviewSettings();
+  return <div data-testid="active-mode">{activeDisplayMode}</div>;
+}
+
+function PreviewHarness() {
+  const { doc } = useEditorContext();
+  return (
+    <PreviewSettingsProvider doc={doc}>
+      <PreviewModeSwitch />
+      <ModeProbe />
+    </PreviewSettingsProvider>
+  );
+}
+
+function renderPreviewControls(markdown: string) {
+  render(
+    <EditorProvider initialMarkdown={markdown}>
+      <PreviewHarness />
+    </EditorProvider>,
+  );
+}
+
+afterEach(() => cleanup());
+
+describe('PreviewModeSwitch', () => {
+  it('labels the plain document preview as Document and the styled view as Page', () => {
+    renderPreviewControls('# Hello');
+
+    const labels = screen
+      .getAllByRole('button')
+      .map((button) => button.textContent)
+      .filter(Boolean);
+
+    expect(labels).toEqual(['Video', 'Slideshow', 'Page', 'Document']);
+
+    fireEvent.click(screen.getByRole('button', { name: 'Document' }));
+    expect(screen.getByTestId('active-mode').textContent).toBe('page');
+
+    fireEvent.click(screen.getByRole('button', { name: 'Page' }));
+    expect(screen.getByTestId('active-mode').textContent).toBe('linear');
+  });
+
+  it('maps product-facing display-mode frontmatter to the correct renderer values', async () => {
+    renderPreviewControls('---\ndisplay-mode: document\n---\n\n# Hello');
+
+    await waitFor(() => {
+      expect(screen.getByTestId('active-mode').textContent).toBe('page');
+    });
+    expect(screen.getByRole('button', { name: 'Document' }).getAttribute('aria-pressed')).toBe(
+      'true',
+    );
+
+    cleanup();
+    renderPreviewControls('---\ndisplay-mode: page\n---\n\n# Hello');
+
+    await waitFor(() => {
+      expect(screen.getByTestId('active-mode').textContent).toBe('linear');
+    });
+    expect(screen.getByRole('button', { name: 'Page' }).getAttribute('aria-pressed')).toBe('true');
+  });
+});

package/src/__tests__/recorderMediaInsert.test.ts

@@ -0,0 +1,86 @@
+import { Editor } from '@tiptap/core';
+import Document from '@tiptap/extension-document';
+import Paragraph from '@tiptap/extension-paragraph';
+import Text from '@tiptap/extension-text';
+import OrderedList from '@tiptap/extension-ordered-list';
+import ListItem from '@tiptap/extension-list-item';
+import { describe, expect, it } from 'vitest';
+import { parseMarkdown } from '@bendyline/squisq/markdown';
+import { markdownToDoc, flattenBlocks } from '@bendyline/squisq/doc';
+import { tiptapToMarkdown } from '../tiptapBridge';
+import { insertMediaBlock } from '../recorder/insertMediaBlock';
+import { collectEmbeddedMedia } from '../embeddedMedia';
+import { TiptapVideo } from '../tiptap/TiptapVideo';
+
+/**
+ * Regression: a recorded clip used to vanish from the markdown source
+ * (and therefore the timeline) when the editor caret sat inside a list
+ * item. The recorder inserts a block-level `<video>` atom; a plain
+ * `insertContent` nests it inside the `<li>`, and `tiptapToMarkdown`'s
+ * list serializer emits only the item's inline text — silently dropping
+ * the nested media. `insertMediaBlock` lifts the insertion to the
+ * top level so the tag round-trips.
+ */
+function makeEditor() {
+  return new Editor({
+    extensions: [Document, Paragraph, Text, OrderedList, ListItem, TiptapVideo],
+    content: '<ol><li><p>First</p></li><li><p>Second</p></li></ol>',
+  });
+}
+
+/** Put the caret at the end of the last list item — where the recorder
+ * modal typically leaves it after the user selected a list-bearing block. */
+function caretInLastListItem(editor: Editor) {
+  editor.commands.focus('end');
+}
+
+describe('recorder media insertion (caret inside a list)', () => {
+  it('a plain insertContent buries the video as an indented continuation of the <li>', () => {
+    const editor = makeEditor();
+    caretInLastListItem(editor);
+    editor
+      .chain()
+      .focus()
+      .insertContent({ type: 'video', attrs: { src: 'video/clip.webm', controls: true } })
+      .run();
+    const md = tiptapToMarkdown(editor.getHTML());
+    editor.destroy();
+    // The hardened serializer no longer drops it, but it lands nested
+    // inside the list item (indented continuation) rather than as its
+    // own block — which is why the recorder uses `insertMediaBlock`.
+    expect(md).toMatch(/\n {2,}<video/);
+  });
+
+  it('insertMediaBlock places the video as a top-level block after the list', () => {
+    const editor = makeEditor();
+    caretInLastListItem(editor);
+    insertMediaBlock(editor, {
+      type: 'video',
+      attrs: { src: 'video/clip.webm', controls: true, width: 480 },
+    });
+    const md = tiptapToMarkdown(editor.getHTML());
+    editor.destroy();
+    // The list is preserved and the clip sits at the document level
+    // (start of line, not indented under a bullet).
+    expect(md).toContain('1. First');
+    expect(md).toContain('2. Second');
+    expect(md).toMatch(/^<video src="video\/clip\.webm"/m);
+  });
+});
+
+describe('hardened list serializer: nested media round-trips to a detectable clip', () => {
+  it('a <video> left inside a list item still parses back as embedded media', () => {
+    // Even when media ends up nested in a list item (drag/paste, not the
+    // recorder path), the serializer keeps it — and the markdown re-parses
+    // to a block whose embedded media the timeline can surface.
+    const md = tiptapToMarkdown(
+      '<h2>Section</h2><ol><li><p>Step</p><video src="video/clip.webm" controls=""></video></li></ol>',
+    );
+    expect(md).toContain('<video');
+
+    const doc = markdownToDoc(parseMarkdown(md));
+    const blocks = flattenBlocks(doc.blocks);
+    const total = blocks.reduce((s, b) => s + collectEmbeddedMedia(b).length, 0);
+    expect(total).toBe(1);
+  });
+});

package/src/__tests__/templateAnnotationRoundTrip.test.ts

@@ -31,4 +31,22 @@ describe('Template annotation round-trip', () => {
     expect(md).not.toContain('squisq-template-badge');
     expect(md).not.toContain('Comparison Bar'); // CSS-rendered label shouldn't bleed
   });
+
+  it('does not leak the block-properties badge into markdown', () => {
+    // The props badge is an empty CSS-painted span rendered alongside the
+    // template badge (and on plain headings, the empty template badge). It
+    // must serialize to nothing — no stray `*`/`**` from an `<i>`, no span.
+    const tiptapRendered =
+      '<h2 data-block-attrs="transition=fade">' +
+      '<span class="squisq-heading-content">Intro</span>' +
+      '<span class="squisq-template-badge squisq-template-badge--empty" contenteditable="false"></span>' +
+      '<span class="squisq-props-badge" contenteditable="false" data-props-summary="Fade · 1:30 start"></span>' +
+      '</h2>';
+    const md = tiptapToMarkdown(tiptapRendered).trim();
+    expect(md).toBe('## Intro {transition=fade}');
+    expect(md).not.toContain('squisq-props-badge');
+    expect(md).not.toContain('*');
+    // The CSS-painted summary lives in a data attribute; it must not bleed.
+    expect(md).not.toContain('start');
+  });
 });

package/src/__tests__/templatePickerMetadata.test.ts

@@ -0,0 +1,32 @@
+import { describe, it, expect } from 'vitest';
+import { TEMPLATE_METADATA } from '@bendyline/squisq/doc';
+import { TEMPLATE_ENTRIES } from '../TemplatePicker';
+
+/**
+ * The TemplatePicker gallery must stay 1:1 with core's TEMPLATE_METADATA so a
+ * template added to the core registry can never silently fail to appear in the
+ * editor. Core owns the canonical id list + labels + descriptions; the picker
+ * adds only the per-id preview icon.
+ */
+describe('TemplatePicker ↔ core TEMPLATE_METADATA', () => {
+  it('lists the same ids in the same order as TEMPLATE_METADATA', () => {
+    const pickerNames = TEMPLATE_ENTRIES.map((e) => e.name);
+    const metadataNames = Object.keys(TEMPLATE_METADATA);
+    expect(pickerNames).toEqual(metadataNames);
+  });
+
+  it('uses the canonical label and description for every entry', () => {
+    for (const entry of TEMPLATE_ENTRIES) {
+      const meta = TEMPLATE_METADATA[entry.name];
+      expect(meta, `missing core metadata for picker entry "${entry.name}"`).toBeTruthy();
+      expect(entry.label, `label drift for "${entry.name}"`).toBe(meta.label);
+      expect(entry.description, `description drift for "${entry.name}"`).toBe(meta.description);
+    }
+  });
+
+  it('provides a preview icon for every entry', () => {
+    for (const entry of TEMPLATE_ENTRIES) {
+      expect(entry.icon, `missing icon for "${entry.name}"`).toBeTruthy();
+    }
+  });
+});

package/src/__tests__/timelineSource.test.ts

@@ -0,0 +1,134 @@
+import { describe, expect, it } from 'vitest';
+import { parseMarkdown } from '@bendyline/squisq/markdown';
+import { markdownToDoc } from '@bendyline/squisq/doc';
+import {
+  formatSeconds,
+  setBlockDurationInSource,
+  setMediaClipInSource,
+  buildClipAnnotation,
+  placeClipInBlock,
+} from '../timelineSource';
+
+/** Re-parse and read a block's duration to confirm the edit took effect. */
+function durationOf(source: string, blockIndex: number): number {
+  const doc = markdownToDoc(parseMarkdown(source), { articleId: 't' });
+  return doc.blocks[blockIndex].duration;
+}
+
+describe('formatSeconds', () => {
+  it('keeps integers bare and rounds fractions', () => {
+    expect(formatSeconds(8)).toBe('8');
+    expect(formatSeconds(8.5)).toBe('8.5');
+    expect(formatSeconds(8.499)).toBe('8.5');
+    expect(formatSeconds(-3)).toBe('0');
+  });
+});
+
+describe('setBlockDurationInSource', () => {
+  it('inserts the duration on a bare heading in the squiggly form', () => {
+    const src = '# Intro\n\nBody.\n';
+    const next = setBlockDurationInSource(src, 1, 12)!;
+    expect(next).toContain('# Intro {[duration=12]}');
+    expect(durationOf(next, 0)).toBe(12);
+  });
+
+  it('folds the duration into an existing template annotation', () => {
+    const src = '# Title {[sectionHeader]}\n\nBody.\n';
+    const next = setBlockDurationInSource(src, 1, 7)!;
+    expect(next).toContain('{[sectionHeader duration=7]}');
+    expect(durationOf(next, 0)).toBe(7);
+  });
+
+  it('updates an existing squiggly duration in place', () => {
+    const src = '# Intro {[duration=5]}\n\nBody.\n';
+    const next = setBlockDurationInSource(src, 1, 9)!;
+    expect(next).toContain('{[duration=9]}');
+    expect(next).not.toContain('duration=5');
+    expect(durationOf(next, 0)).toBe(9);
+  });
+
+  it('migrates a legacy Pandoc duration to squiggly, preserving id/classes', () => {
+    const src = '# Intro {#intro .hero duration=5}\n\nBody.\n';
+    const next = setBlockDurationInSource(src, 1, 9)!;
+    expect(next).toContain('#intro');
+    expect(next).toContain('.hero');
+    expect(next).toContain('{[duration=9]}');
+    // The stale Pandoc duration is gone so the two forms can't disagree.
+    expect(next).not.toMatch(/\{[^[]*duration=/);
+    expect(durationOf(next, 0)).toBe(9);
+  });
+
+  it('returns null for a non-heading line', () => {
+    expect(setBlockDurationInSource('not a heading\n', 1, 5)).toBeNull();
+  });
+});
+
+describe('setMediaClipInSource', () => {
+  const src = '# B {duration=20}\n\n{[audio src=a.mp3 startAt=2]}\n';
+
+  it('patches startAt on a media annotation', () => {
+    const next = setMediaClipInSource(src, 3, { startAt: 6 })!;
+    expect(next).toContain('{[audio src=a.mp3 startAt=6]}');
+    const doc = markdownToDoc(parseMarkdown(next), { articleId: 't' });
+    expect(doc.blocks[0].media![0].startAt).toBe(6);
+  });
+
+  it('adds clipEnd and toggles spillover, keeping src', () => {
+    const next = setMediaClipInSource(src, 3, { clipEnd: 30, spillover: true })!;
+    expect(next).toContain('src=a.mp3');
+    expect(next).toContain('clipEnd=30');
+    expect(next).toContain('spillover=true');
+  });
+
+  it('removes a key when patched with null', () => {
+    const withSpill = setMediaClipInSource(src, 3, { spillover: true })!;
+    const removed = setMediaClipInSource(withSpill, 3, { spillover: null })!;
+    expect(removed).not.toContain('spillover');
+  });
+
+  it('returns null for a non-media line', () => {
+    expect(setMediaClipInSource(src, 1, { startAt: 1 })).toBeNull();
+  });
+});
+
+describe('buildClipAnnotation', () => {
+  it('emits a minimal annotation', () => {
+    expect(buildClipAnnotation({ kind: 'video', src: 'r.webm' }, 0)).toBe('{[video src=r.webm]}');
+  });
+
+  it('includes timing fields when set', () => {
+    expect(
+      buildClipAnnotation({ kind: 'audio', src: 'a.mp3', clipEnd: 8, spillover: true }, 5),
+    ).toBe('{[audio src=a.mp3 startAt=5 clipEnd=8 spillover=true]}');
+  });
+});
+
+describe('placeClipInBlock', () => {
+  // Lines: 1 "# One {duration=10}", 2 "", 3 "<video src=r.webm></video>",
+  //        4 "", 5 "# Two {duration=10}", 6 "", 7 "body"
+  const src =
+    '# One {duration=10}\n\n<video src="r.webm"></video>\n\n# Two {duration=10}\n\nbody\n';
+
+  it('converts an embed to an annotation in place (same block)', () => {
+    const next = placeClipInBlock(src, 3, 1, { kind: 'video', src: 'r.webm', clipEnd: 10 }, 0)!;
+    expect(next).toContain('{[video src=r.webm clipEnd=10]}');
+    expect(next).not.toContain('<video');
+    // Still under block One (line 1), before block Two.
+    expect(next.indexOf('{[video')).toBeLessThan(next.indexOf('# Two'));
+  });
+
+  it('relocates the clip into a different (earlier/later) block', () => {
+    // Move the embed (line 3, in block One) into block Two (heading line 5).
+    const next = placeClipInBlock(src, 3, 5, { kind: 'video', src: 'r.webm', clipEnd: 4 }, 2)!;
+    expect(next).not.toContain('<video');
+    // The annotation now sits after block Two's heading.
+    const twoIdx = next.indexOf('# Two');
+    const clipIdx = next.indexOf('{[video');
+    expect(clipIdx).toBeGreaterThan(twoIdx);
+    expect(next).toContain('startAt=2');
+    // Re-parsing attaches it to block Two as a media clip.
+    const doc = markdownToDoc(parseMarkdown(next), { articleId: 't' });
+    expect(doc.blocks[1].media?.[0]).toMatchObject({ src: 'r.webm', startAt: 2, anchor: 'block' });
+    expect(doc.blocks[0].media).toBeUndefined();
+  });
+});