@bendyline/squisq-editor-react 1.5.3 → 1.6.1

package/src/WysiwygEditor.tsx

@@ -10,7 +10,7 @@
  * and code blocks.
  */
 
-import { useEffect, useMemo, useRef, useState } from 'react';
+import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
 import type { CSSProperties } from 'react';
 import { useEditor, EditorContent } from '@tiptap/react';
 import StarterKit from '@tiptap/starter-kit';
@@ -24,13 +24,25 @@ import Link from '@tiptap/extension-link';
 import Placeholder from '@tiptap/extension-placeholder';
 import { resolveFontFamily, FONT_FALLBACKS } from '@bendyline/squisq/schemas';
 import { HeadingWithTemplate } from './TemplateAnnotation';
+import { DiagramExtension } from './diagram/DiagramExtension';
+import { SceneBlockExtension } from './scene/SceneBlockExtension';
 import { InlineIcon } from './InlineIcon';
 import { ImageWithMediaProvider } from './ImageNodeView';
 import { TiptapVideo } from './tiptap/TiptapVideo';
 import { TiptapAudio } from './tiptap/TiptapAudio';
 import { TemplateBadgePopover, TEMPLATE_NAMES } from './TemplatePicker';
+import { BlockPropertiesPopover } from './BlockPropertiesPopover';
+import {
+  CustomTemplateProvider,
+  TemplateDesigner,
+  type DesignerSaveTarget,
+} from './customTemplates';
+import { saveLibraryTemplate } from './customTemplates/library';
+import { useDocCustomTemplates } from './customTemplates/useDocCustomTemplates';
+import type { CustomTemplateDefinition } from '@bendyline/squisq/schemas';
 import { profileBlockContents, recommendTemplatesForBlock } from '@bendyline/squisq/recommend';
 import { findBlockSliceByHeadingIndex } from './blockSlice';
+import { stripFrontmatter } from './frontmatter';
 import { useEditorContext } from './EditorContext';
 import { buildMentionExtension } from './MentionExtension';
 import { markdownToTiptap, tiptapToMarkdown } from './tiptapBridge';
@@ -38,18 +50,6 @@ import { looksLikeMarkdown } from './detectMarkdown';
 import { SQUISQ_MEDIA_MIME, parseSquisqMediaPayload } from './mediaDragMime';
 import { usePreviewSettingsOptional } from './PreviewControls';
 
-// ── Frontmatter helpers ────────────────────────────────────────────
-
-/** Regex matching a YAML frontmatter block at the start of the document. */
-const FRONTMATTER_RE = /^---\r?\n([\s\S]*?)\r?\n---\r?\n?/;
-
-/** Strip YAML frontmatter from markdown, returning both parts. */
-function stripFrontmatter(md: string): { body: string; frontmatter: string } {
-  const m = md.match(FRONTMATTER_RE);
-  if (!m) return { body: md, frontmatter: '' };
-  return { body: md.slice(m[0].length), frontmatter: m[0] };
-}
-
 /**
  * Rotating placeholder prompts shown when the editor is empty. One is
  * picked at random per editor mount. Hosts can override by passing the
@@ -101,14 +101,38 @@ export function WysiwygEditor({
   readOnly = false,
 }: WysiwygEditorProps) {
   const {
-    markdownSource,
-    setMarkdownSource,
+    editorSource,
+    setEditorSource,
     setTiptapEditor,
     mediaProvider,
     mentionProvider,
     blockTagsVisible,
     themeInheritance,
   } = useEditorContext();
+  // Custom templates inlined in the active doc's frontmatter + the
+  // persist callback that writes a new list back into the source.
+  const { docTemplates, onDocTemplatesChange } = useDocCustomTemplates();
+  // Designer modal visibility. `null` when closed; `{ initial }` when
+  // open. `initial` is undefined for a "+ New" flow or set to an
+  // existing template to edit it.
+  const [designerState, setDesignerState] = useState<{ initial?: CustomTemplateDefinition } | null>(
+    null,
+  );
+  const handleDesignerSave = useCallback(
+    (def: CustomTemplateDefinition, target: DesignerSaveTarget) => {
+      if (target === 'doc') {
+        const existingIdx = docTemplates.findIndex((t) => t.name === def.name);
+        const next =
+          existingIdx >= 0
+            ? docTemplates.map((t, i) => (i === existingIdx ? def : t))
+            : [...docTemplates, def];
+        onDocTemplatesChange(next);
+      } else {
+        saveLibraryTemplate(def);
+      }
+    },
+    [docTemplates, onDocTemplatesChange],
+  );
   // Keep a ref so the mention extension — created once at editor mount —
   // always sees the latest provider. Swapping projects changes
   // the provider without remounting the editor.
@@ -120,15 +144,18 @@ export function WysiwygEditor({
   // from EMPTY_PROMPTS. Re-renders don't reshuffle.
   const resolvedPlaceholder = useMemo(() => placeholder ?? pickEmptyPrompt(), [placeholder]);
   const isExternalUpdate = useRef(false);
-  const lastSourceRef = useRef(markdownSource);
+  const lastSourceRef = useRef(editorSource);
   // Keep a ref so the editor's drop/paste handlers (created once) always
   // see the current MediaProvider without needing to recreate the editor.
   const mediaProviderRef = useRef(mediaProvider);
   useEffect(() => {
     mediaProviderRef.current = mediaProvider;
   }, [mediaProvider]);
-  // Preserve frontmatter across edits — hidden from WYSIWYG but prepended on save
-  const frontmatterRef = useRef(stripFrontmatter(markdownSource).frontmatter);
+  // Preserve frontmatter across edits — hidden from WYSIWYG but prepended on
+  // save. In block mode the bound slice carries no frontmatter, so this is an
+  // empty string and the splice in `setEditorSource` keeps the doc's real
+  // frontmatter intact.
+  const frontmatterRef = useRef(stripFrontmatter(editorSource).frontmatter);
   // Stash the latest submit callback so the editor's handleKeyDown (bound
   // once at creation) always sees the current value.
   const submitOnEnterRef = useRef(submitOnEnter);
@@ -147,6 +174,8 @@ export function WysiwygEditor({
         },
       }),
       HeadingWithTemplate.configure({ levels: [1, 2, 3, 4, 5, 6] }),
+      DiagramExtension,
+      SceneBlockExtension,
       Table.configure({ resizable: true }),
       TableRow,
       TableCell,
@@ -165,14 +194,14 @@ export function WysiwygEditor({
       buildMentionExtension(() => mentionProviderRef.current),
       InlineIcon,
     ],
-    content: markdownToTiptap(stripFrontmatter(markdownSource).body),
+    content: markdownToTiptap(stripFrontmatter(editorSource).body),
     onUpdate: ({ editor: ed }) => {
       if (isExternalUpdate.current) return;
       const html = ed.getHTML();
       const bodyMd = tiptapToMarkdown(html);
       const newSource = frontmatterRef.current + bodyMd;
       lastSourceRef.current = newSource;
-      setMarkdownSource(newSource);
+      setEditorSource(newSource);
     },
     editorProps: {
       attributes: {
@@ -330,6 +359,12 @@ export function WysiwygEditor({
     headingPos: number;
     headingIndex: number;
   } | null>(null);
+  const [propsMenu, setPropsMenu] = useState<{
+    rect: DOMRect;
+    headingPos: number;
+    blockAttrs: string | null;
+    templateParams: string | null;
+  } | null>(null);
 
   useEffect(() => {
     if (!editor) return;
@@ -338,7 +373,9 @@ export function WysiwygEditor({
     const onClick = (e: MouseEvent) => {
       const target = e.target as HTMLElement | null;
       if (!target) return;
-      const badge = target.closest('.squisq-template-badge') as HTMLElement | null;
+      const propsBadge = target.closest('.squisq-props-badge') as HTMLElement | null;
+      const templateBadge = target.closest('.squisq-template-badge') as HTMLElement | null;
+      const badge = propsBadge ?? templateBadge;
       if (!badge || !root.contains(badge)) return;
       e.preventDefault();
       e.stopPropagation();
@@ -357,8 +394,22 @@ export function WysiwygEditor({
       const headingPos = Math.max(0, pos - 1);
       const node = editor.state.doc.nodeAt(headingPos);
       if (!node || node.type.name !== 'heading') return;
-      // Count how many headings precede this one so the markdown-source
-      // slice helper can locate the matching heading by index.
+
+      // Block-properties badge → open the properties palette.
+      if (propsBadge) {
+        setBadgeMenu(null);
+        setPropsMenu({
+          rect: badge.getBoundingClientRect(),
+          headingPos,
+          blockAttrs: (node.attrs.dataBlockAttrs as string | null) ?? null,
+          templateParams: (node.attrs.dataTemplateParams as string | null) ?? null,
+        });
+        return;
+      }
+
+      // Template badge → open the template gallery. Count how many headings
+      // precede this one so the markdown-source slice helper can locate the
+      // matching heading by index.
       let headingIndex = 0;
       let count = 0;
       editor.state.doc.descendants((n, p) => {
@@ -369,6 +420,7 @@ export function WysiwygEditor({
         }
         count++;
       });
+      setPropsMenu(null);
       setBadgeMenu({
         rect: badge.getBoundingClientRect(),
         template: (node.attrs.dataTemplate as string | null) ?? '',
@@ -380,20 +432,29 @@ export function WysiwygEditor({
     return () => root.removeEventListener('mousedown', onClick);
   }, [editor]);
 
-  // Sync external changes into Tiptap
+  // Sync external changes into Tiptap. `editorSource` also changes when the
+  // user navigates to a different block in block-at-a-time mode, so this same
+  // path reloads the card with the newly selected block's slice.
   useEffect(() => {
     if (!editor) return;
-    // Only update if the source changed externally (not from our own onUpdate)
-    if (markdownSource !== lastSourceRef.current) {
-      isExternalUpdate.current = true;
-      const { body, frontmatter } = stripFrontmatter(markdownSource);
-      frontmatterRef.current = frontmatter;
-      const content = markdownToTiptap(body);
-      editor.commands.setContent(content);
-      lastSourceRef.current = markdownSource;
-      isExternalUpdate.current = false;
+    if (editorSource === lastSourceRef.current) return;
+    // In block/timeline mode `setEditorSource` normalizes the slice's trailing
+    // whitespace (a `\n\n` before the next block) before splicing, so the
+    // re-extracted `editorSource` differs from what we just emitted by trailing
+    // whitespace only. Re-setting content for that would reset the caret to the
+    // end on every keystroke — so only reload when the body actually changed.
+    if (editorSource.replace(/\s+$/, '') === lastSourceRef.current.replace(/\s+$/, '')) {
+      lastSourceRef.current = editorSource;
+      return;
     }
-  }, [markdownSource, editor]);
+    isExternalUpdate.current = true;
+    const { body, frontmatter } = stripFrontmatter(editorSource);
+    frontmatterRef.current = frontmatter;
+    const content = markdownToTiptap(body);
+    editor.commands.setContent(content);
+    lastSourceRef.current = editorSource;
+    isExternalUpdate.current = false;
+  }, [editorSource, editor]);
 
   // Match the WYSIWYG editor's appearance to the active Squisq theme
   // when one is set in frontmatter or picked in the preview dropdown.
@@ -432,37 +493,72 @@ export function WysiwygEditor({
   }, [activeTheme, themeInheritance]);
 
   return (
-    <div
-      className={`squisq-wysiwyg-container${className ? ` ${className}` : ''}`}
-      style={{ width: '100%', height: '100%', overflow: 'auto', ...themeStyle }}
-      data-testid="wysiwyg-container"
-      data-block-tags={blockTagsVisible ? 'visible' : 'hidden'}
-      data-theme-inheritance={themeInheritance}
-      ref={containerRef}
-    >
-      <EditorContent editor={editor} style={{ height: '100%' }} />
-      {badgeMenu && (
-        <TemplateBadgePopover
-          anchorRect={badgeMenu.rect}
-          value={badgeMenu.template}
-          recommended={(() => {
-            const slice = findBlockSliceByHeadingIndex(markdownSource, badgeMenu.headingIndex);
-            if (!slice) return undefined;
-            const profile = profileBlockContents(slice);
-            return recommendTemplatesForBlock(profile, TEMPLATE_NAMES).recommended;
-          })()}
-          onChange={(name) => {
-            if (!editor) return;
-            const tr = editor.state.tr.setNodeMarkup(badgeMenu.headingPos, undefined, {
-              ...editor.state.doc.nodeAt(badgeMenu.headingPos)?.attrs,
-              dataTemplate: name === '' ? null : name,
-            });
-            editor.view.dispatch(tr);
-          }}
-          onClose={() => setBadgeMenu(null)}
-        />
-      )}
-    </div>
+    <CustomTemplateProvider docTemplates={docTemplates} onDocTemplatesChange={onDocTemplatesChange}>
+      <div
+        className={`squisq-wysiwyg-container${className ? ` ${className}` : ''}`}
+        style={{ width: '100%', height: '100%', overflow: 'auto', ...themeStyle }}
+        data-testid="wysiwyg-container"
+        data-block-tags={blockTagsVisible ? 'visible' : 'hidden'}
+        data-theme-inheritance={themeInheritance}
+        ref={containerRef}
+      >
+        <EditorContent editor={editor} style={{ height: '100%' }} />
+        {badgeMenu && (
+          <TemplateBadgePopover
+            anchorRect={badgeMenu.rect}
+            value={badgeMenu.template}
+            recommended={(() => {
+              // `headingIndex` is counted within the mounted Tiptap doc, which
+              // reflects `editorSource` — the active block's slice in block
+              // mode, the full document otherwise.
+              const slice = findBlockSliceByHeadingIndex(editorSource, badgeMenu.headingIndex);
+              if (!slice) return undefined;
+              const profile = profileBlockContents(slice);
+              return recommendTemplatesForBlock(profile, TEMPLATE_NAMES).recommended;
+            })()}
+            onOpenDesigner={() => {
+              setBadgeMenu(null);
+              setDesignerState({});
+            }}
+            onChange={(name) => {
+              if (!editor) return;
+              const tr = editor.state.tr.setNodeMarkup(badgeMenu.headingPos, undefined, {
+                ...editor.state.doc.nodeAt(badgeMenu.headingPos)?.attrs,
+                dataTemplate: name === '' ? null : name,
+              });
+              editor.view.dispatch(tr);
+            }}
+            onClose={() => setBadgeMenu(null)}
+          />
+        )}
+        {propsMenu && (
+          <BlockPropertiesPopover
+            anchorRect={propsMenu.rect}
+            blockAttrs={propsMenu.blockAttrs}
+            templateParams={propsMenu.templateParams}
+            onChange={(nextInner) => {
+              if (!editor) return;
+              const current = editor.state.doc.nodeAt(propsMenu.headingPos);
+              if (!current || current.type.name !== 'heading') return;
+              const tr = editor.state.tr.setNodeMarkup(propsMenu.headingPos, undefined, {
+                ...current.attrs,
+                dataBlockAttrs: nextInner,
+              });
+              editor.view.dispatch(tr);
+            }}
+            onClose={() => setPropsMenu(null)}
+          />
+        )}
+        {designerState && (
+          <TemplateDesigner
+            initial={designerState.initial}
+            onSave={handleDesignerSave}
+            onClose={() => setDesignerState(null)}
+            mediaProvider={mediaProvider}
+          />
+        )}
+      </div>
+    </CustomTemplateProvider>
   );
 }
 

package/src/__tests__/blockProperties.test.ts

@@ -0,0 +1,92 @@
+import { describe, it, expect } from 'vitest';
+import {
+  readBlockAttrsParams,
+  readBlockAttrsValue,
+  setBlockAttrsValue,
+  summarizeBlockProps,
+} from '../blockProperties';
+
+describe('readBlockAttrsParams', () => {
+  it('returns empty for null/empty inner', () => {
+    expect(readBlockAttrsParams(null)).toEqual({});
+    expect(readBlockAttrsParams('')).toEqual({});
+  });
+
+  it('parses key=value params (ignoring #id / .class)', () => {
+    expect(readBlockAttrsParams('#intro .lead duration=45 startTime=5')).toEqual({
+      duration: '45',
+      startTime: '5',
+    });
+  });
+});
+
+describe('readBlockAttrsValue', () => {
+  it('reads a single param or empty string', () => {
+    expect(readBlockAttrsValue('duration=45', 'duration')).toBe('45');
+    expect(readBlockAttrsValue('duration=45', 'startTime')).toBe('');
+    expect(readBlockAttrsValue(null, 'duration')).toBe('');
+  });
+});
+
+describe('setBlockAttrsValue', () => {
+  it('adds a param to a fresh block', () => {
+    expect(setBlockAttrsValue(null, 'duration', '45')).toBe('duration=45');
+  });
+
+  it('updates an existing param in place, preserving order and other keys', () => {
+    expect(setBlockAttrsValue('#intro duration=10 startTime=2', 'duration', '20')).toBe(
+      '#intro duration=20 startTime=2',
+    );
+  });
+
+  it('removes a param when set to empty, dropping the block when nothing remains', () => {
+    expect(setBlockAttrsValue('duration=45', 'duration', '')).toBeNull();
+    expect(setBlockAttrsValue('#intro duration=45', 'duration', '  ')).toBe('#intro');
+  });
+
+  it('does not disturb a transition already present', () => {
+    expect(setBlockAttrsValue('transition=fade', 'duration', '3')).toBe(
+      'transition=fade duration=3',
+    );
+  });
+
+  it('round-trips through read', () => {
+    const inner = setBlockAttrsValue(setBlockAttrsValue(null, 'duration', '12'), 'startTime', '4');
+    expect(readBlockAttrsValue(inner, 'duration')).toBe('12');
+    expect(readBlockAttrsValue(inner, 'startTime')).toBe('4');
+  });
+});
+
+describe('summarizeBlockProps', () => {
+  it('returns empty when nothing is set', () => {
+    expect(summarizeBlockProps(null, null)).toBe('');
+    expect(summarizeBlockProps('#intro', null)).toBe('');
+  });
+
+  it('names the transition using its friendly label', () => {
+    expect(summarizeBlockProps('transition=doors', null)).toBe('Doors');
+  });
+
+  it('formats start time and duration as m:ss', () => {
+    expect(summarizeBlockProps('startTime=90', null)).toBe('1:30 start');
+    expect(summarizeBlockProps('duration=200', null)).toBe('3:20 long');
+  });
+
+  it('accepts already-formatted m:ss time values', () => {
+    expect(summarizeBlockProps('startTime=1:30', null)).toBe('1:30 start');
+  });
+
+  it('joins all set properties in order with a middot', () => {
+    expect(summarizeBlockProps('transition=vortex startTime=90 duration=200', null)).toBe(
+      'Vortex · 1:30 start · 3:20 long',
+    );
+  });
+
+  it('reads a hand-typed transition from the {[…]} params', () => {
+    expect(summarizeBlockProps(null, 'title transition=zoom')).toBe('Zoom');
+  });
+
+  it('normalizes a transition alias spelling for the label', () => {
+    expect(summarizeBlockProps('transition=Doors', null)).toBe('Doors');
+  });
+});

package/src/__tests__/blockRange.test.ts

@@ -0,0 +1,105 @@
+import { describe, expect, it } from 'vitest';
+import {
+  getBlockSlices,
+  spliceBlock,
+  lineToOffset,
+  offsetToLine,
+  sliceIndexAtOffset,
+} from '../blockRange';
+
+describe('getBlockSlices', () => {
+  it('returns one slice per heading in document order', () => {
+    const md = '# One\n\nalpha\n\n# Two\n\nbeta\n';
+    const slices = getBlockSlices(md);
+    expect(slices.map((s) => s.text)).toEqual(['# One\n\nalpha\n\n', '# Two\n\nbeta\n']);
+  });
+
+  it('starts a new slice at every heading depth (children are not folded in)', () => {
+    const md = '# Parent\n\nintro\n\n## Child\n\nbody\n';
+    const slices = getBlockSlices(md);
+    expect(slices).toHaveLength(2);
+    expect(slices[0].text).toBe('# Parent\n\nintro\n\n');
+    expect(slices[1].text).toBe('## Child\n\nbody\n');
+  });
+
+  it('includes leading content before the first heading as a preamble slice', () => {
+    const md = 'preamble text\n\n# First\n\nbody\n';
+    const slices = getBlockSlices(md);
+    expect(slices).toHaveLength(2);
+    expect(slices[0].text).toBe('preamble text\n\n');
+    expect(slices[1].text).toBe('# First\n\nbody\n');
+  });
+
+  it('skips a whitespace-only preamble', () => {
+    const md = '\n\n# Only\n\nbody\n';
+    const slices = getBlockSlices(md);
+    expect(slices).toHaveLength(1);
+    expect(slices[0].text).toBe('# Only\n\nbody\n');
+  });
+
+  it('treats a heading-less document as a single slice', () => {
+    const md = 'just a paragraph\n\nand another\n';
+    const slices = getBlockSlices(md);
+    expect(slices).toHaveLength(1);
+    expect(slices[0].text).toBe(md);
+  });
+
+  it('treats an empty document as a single (empty) slice', () => {
+    const slices = getBlockSlices('');
+    expect(slices).toHaveLength(1);
+    expect(slices[0].text).toBe('');
+  });
+
+  it('never folds frontmatter into a slice', () => {
+    const md = '---\ntitle: Hi\n---\n# Heading\n\nbody\n';
+    const slices = getBlockSlices(md);
+    expect(slices).toHaveLength(1);
+    expect(slices[0].text).toBe('# Heading\n\nbody\n');
+    // The frontmatter stays in the untouched prefix.
+    expect(md.slice(0, slices[0].range.startOffset)).toBe('---\ntitle: Hi\n---\n');
+  });
+});
+
+describe('spliceBlock round-trips', () => {
+  const cases = [
+    '# One\n\nalpha\n\n# Two\n\nbeta\n',
+    '# Parent\n\nintro\n\n## Child\n\nbody\n',
+    'preamble text\n\n# First\n\nbody\n',
+    '---\ntitle: Hi\n---\n# Heading\n\nbody\n',
+    'no headings at all\n',
+  ];
+
+  it('re-splicing a slice with its own text reproduces the source exactly', () => {
+    for (const md of cases) {
+      const slices = getBlockSlices(md);
+      for (const slice of slices) {
+        expect(spliceBlock(md, slice.range, slice.text)).toBe(md);
+      }
+    }
+  });
+
+  it('splices an edited block back into the full document', () => {
+    const md = '# One\n\nalpha\n\n# Two\n\nbeta\n';
+    const slices = getBlockSlices(md);
+    const edited = spliceBlock(md, slices[0].range, '# One\n\nalpha edited\n\n');
+    expect(edited).toBe('# One\n\nalpha edited\n\n# Two\n\nbeta\n');
+  });
+});
+
+describe('line/offset helpers', () => {
+  const md = '# One\n\nalpha\n\n# Two\n';
+
+  it('maps lines to offsets and back', () => {
+    // Line 5 is the "# Two" heading.
+    const offset = lineToOffset(md, 5);
+    expect(md.slice(offset, offset + 5)).toBe('# Two');
+    expect(offsetToLine(md, offset)).toBe(5);
+  });
+
+  it('finds the slice index containing an offset', () => {
+    const slices = getBlockSlices(md);
+    const secondHeadingOffset = lineToOffset(md, 5);
+    expect(sliceIndexAtOffset(slices, secondHeadingOffset)).toBe(1);
+    expect(sliceIndexAtOffset(slices, 0)).toBe(0);
+  });
+});

package/src/__tests__/buildPreviewDocTransition.test.ts

@@ -0,0 +1,73 @@
+import { describe, it, expect } from 'vitest';
+import { parseMarkdown } from '@bendyline/squisq/markdown';
+import { markdownToDoc } from '@bendyline/squisq/doc';
+import type { Transition } from '@bendyline/squisq/schemas';
+import { buildPreviewDoc } from '../buildPreviewDoc';
+
+function previewSlides(md: string) {
+  const doc = markdownToDoc(parseMarkdown(md), { articleId: 't' });
+  return buildPreviewDoc(doc).blocks as unknown as Array<{ transition?: Transition }>;
+}
+
+describe('buildPreviewDoc transition mapping', () => {
+  it('carries an authored transition through to the player slide', () => {
+    // Transition written the way the toolbar / properties palette writes it:
+    // into the heading's Pandoc `{…}` attribute block.
+    const md = ['# Intro', '', '# Second {transition=vortex}', '', 'body'].join('\n');
+    const slides = previewSlides(md);
+    expect(slides[1].transition).toEqual({ type: 'vortex' });
+  });
+
+  it('preserves direction and duration on the transition', () => {
+    const md = [
+      '# Intro',
+      '',
+      '# Second {transition=push transitionDirection=up transitionDuration=1.2}',
+    ].join('\n');
+    const slides = previewSlides(md);
+    expect(slides[1].transition).toEqual({ type: 'push', direction: 'up', duration: 1.2 });
+  });
+
+  it('falls back to the default fade for a non-first block with no transition', () => {
+    const md = ['# Intro', '', '# Second'].join('\n');
+    const slides = previewSlides(md);
+    expect(slides[1].transition).toEqual({ type: 'fade', duration: 0.5 });
+  });
+
+  it('leaves the first block without a transition when none is authored', () => {
+    const slides = previewSlides(['# Intro', '', '# Second'].join('\n'));
+    expect(slides[0].transition).toBeUndefined();
+  });
+
+  it('honors a transition authored on the first block', () => {
+    const slides = previewSlides(['# Intro {transition=zoom}', '', '# Second'].join('\n'));
+    expect(slides[0].transition).toEqual({ type: 'zoom' });
+  });
+
+  // The `{[name key=value]}` template-annotation form is the one the editor's
+  // attribute autocomplete advertises for `transition=`. The coerced typed
+  // transition object also rides along as a raw string in the block's
+  // templateData; if that string is spread over the typed field it silently
+  // downgrades `{ type: 'vortex' }` to the string `'vortex'`, which the player
+  // can't animate. These guard that the typed object wins.
+  describe('transition written inside a {[…]} template annotation', () => {
+    it('keeps a bare transition as a typed object, not a raw string', () => {
+      const md = ['# Intro', '', '## Second {[quote transition=vortex]}', '', '> hi'].join('\n');
+      const slides = previewSlides(md);
+      expect(slides[1].transition).toEqual({ type: 'vortex' });
+      expect(typeof slides[1].transition).toBe('object');
+    });
+
+    it('preserves direction and duration from the annotation', () => {
+      const md = [
+        '# Intro',
+        '',
+        '## Second {[factCard transition=push transitionDirection=left transitionDuration=0.8]}',
+        '',
+        'body',
+      ].join('\n');
+      const slides = previewSlides(md);
+      expect(slides[1].transition).toEqual({ type: 'push', direction: 'left', duration: 0.8 });
+    });
+  });
+});