@bendyline/squisq 1.4.1 → 1.5.1

package/src/__tests__/templates.test.ts

@@ -10,6 +10,10 @@ import {
   VIEWPORT_PRESETS,
 } from '../doc/templates/index';
 import type { TemplateBlock } from '../schemas/BlockTemplates';
+import type { TextLayer } from '../schemas/Doc';
+import { getLayers } from '../doc/getLayers';
+import { markdownToDoc } from '../doc/markdownToDoc';
+import { parseMarkdown } from '../markdown/parse';
 
 describe('templateRegistry', () => {
   it('contains all expected templates', () => {
@@ -137,7 +141,7 @@ describe('expandTemplateBlock', () => {
     expect(imageLayer!.position.height).toBe('90%');
   });
 
-  it('expands rightFeature template with image on the right half and right-aligned text left', () => {
+  it('expands rightFeature template with image on the right half and left-aligned text on the left', () => {
     const block: TemplateBlock = {
       template: 'rightFeature',
       id: 'rf-1',
@@ -157,9 +161,11 @@ describe('expandTemplateBlock', () => {
     expect(imageLayer!.position.width).toBe('50%');
     const textLayers = layers.filter((l) => l.type === 'text');
     for (const t of textLayers) {
-      expect(t.position.x).toBe('46%');
-      expect(t.position.anchor).toBe('top-right');
-      expect((t.content as { style: { textAlign?: string } }).style.textAlign).toBe('right');
+      // The mirror lives in the layout only: the text column occupies the
+      // left half, but the running text stays left-aligned for readability.
+      expect(t.position.x).toBe('6%');
+      expect(t.position.anchor).toBe('top-left');
+      expect((t.content as { style: { textAlign?: string } }).style.textAlign).toBe('left');
     }
   });
 
@@ -242,6 +248,75 @@ describe('expandTemplateBlock', () => {
       expect((result.layers ?? []).length).toBeGreaterThanOrEqual(1);
     }
   });
+
+  it('keeps photoGrid media captions compact without placeholder alt labels', () => {
+    const block: TemplateBlock = {
+      template: 'photoGrid',
+      id: 'photo-grid-captions',
+      duration: 10,
+      audioSegment: 0,
+      images: [
+        { src: 'one.jpg', alt: 'A long archival caption for the first image' },
+        { src: 'two.jpg', alt: 'A long archival caption for the second image' },
+        { src: 'three.jpg', alt: 'A long archival caption for the third image' },
+      ],
+      caption:
+        'A long Wikimedia description with source notes, place names, dates, and details that should remain compact.',
+    };
+
+    const context = createTemplateContext(DEFAULT_THEME, 0, 10, VIEWPORT_PRESETS.landscape);
+    const result = expandTemplateBlock(block, context);
+    const layers = result.layers ?? [];
+    const captionLayer = layers.find(
+      (layer): layer is TextLayer => layer.type === 'text' && layer.id === 'caption',
+    );
+
+    expect(layers.some((layer) => layer.id.startsWith('grid-alt-'))).toBe(false);
+    expect(captionLayer).toBeDefined();
+    expect(captionLayer!.content.style.maxLines).toBe(1);
+    expect(captionLayer!.position.width).toBe('78%');
+  });
+
+  it('clamps full-bleed media captions above playback controls', () => {
+    const imageBlock: TemplateBlock = {
+      template: 'imageWithCaption',
+      id: 'image-caption',
+      duration: 10,
+      audioSegment: 0,
+      imageSrc: 'image.jpg',
+      imageAlt: 'Image',
+      caption:
+        'A long Wikimedia description with source notes, place names, dates, and details that should remain compact.',
+    };
+    const videoBlock: TemplateBlock = {
+      template: 'videoWithCaption',
+      id: 'video-caption',
+      duration: 10,
+      audioSegment: 0,
+      videoSrc: 'video.mp4',
+      videoAlt: 'Video',
+      clipStart: 0,
+      clipEnd: 10,
+      caption: imageBlock.caption,
+    };
+
+    const context = createTemplateContext(DEFAULT_THEME, 0, 10, VIEWPORT_PRESETS.landscape);
+    const imageCaption = (expandTemplateBlock(imageBlock, context).layers ?? []).find(
+      (layer): layer is TextLayer => layer.type === 'text' && layer.id === 'caption',
+    );
+    const videoCaption = (expandTemplateBlock(videoBlock, context).layers ?? []).find(
+      (layer): layer is TextLayer => layer.type === 'text' && layer.id === 'caption',
+    );
+
+    expect(imageCaption).toBeDefined();
+    expect(videoCaption).toBeDefined();
+    expect(imageCaption!.content.style.maxLines).toBe(2);
+    expect(videoCaption!.content.style.maxLines).toBe(2);
+    expect(imageCaption!.position.y).toBe('74%');
+    expect(videoCaption!.position.y).toBe('74%');
+    expect(imageCaption!.position.width).toBe('78%');
+    expect(videoCaption!.position.width).toBe('78%');
+  });
 });
 
 describe('expandDocBlocks', () => {
@@ -309,6 +384,145 @@ describe('expandDocBlocks', () => {
     expect((landscape[0].layers ?? []).length).toBeGreaterThan(0);
     expect((portrait[0].layers ?? []).length).toBeGreaterThan(0);
   });
+
+  describe('theme renderStyle wiring', () => {
+    const blocks = (): TemplateBlock[] => [
+      { template: 'title', id: 't-1', duration: 5, audioSegment: 0, title: 'One' },
+      {
+        template: 'imageWithCaption',
+        id: 't-2',
+        duration: 6,
+        audioSegment: 0,
+        imageSrc: 'photo.jpg',
+        imageAlt: 'photo',
+        caption: 'A caption',
+      },
+    ];
+
+    it('fills the theme default transition on blocks after the first, never block 0', () => {
+      const theme = {
+        ...DEFAULT_THEME,
+        renderStyle: {
+          ...DEFAULT_THEME.renderStyle,
+          defaultTransition: { type: 'dissolve' as const, duration: 1.1 },
+        },
+      };
+      const result = expandDocBlocks(blocks(), { theme });
+      expect(result[0].transition).toBeUndefined();
+      expect(result[1].transition).toEqual({ type: 'dissolve', duration: 1.1 });
+    });
+
+    it('never overrides an authored block transition', () => {
+      const theme = {
+        ...DEFAULT_THEME,
+        renderStyle: {
+          ...DEFAULT_THEME.renderStyle,
+          defaultTransition: { type: 'dissolve' as const },
+        },
+      };
+      const authored = blocks();
+      authored[1].transition = { type: 'cut' };
+      const result = expandDocBlocks(authored, { theme });
+      expect(result[1].transition).toEqual({ type: 'cut' });
+    });
+
+    it('scales template animation durations by theme animationSpeed', () => {
+      const theme = {
+        ...DEFAULT_THEME,
+        style: { ...DEFAULT_THEME.style, animationSpeed: 2.0 },
+      };
+      const base = expandDocBlocks(blocks());
+      const slowed = expandDocBlocks(blocks(), { theme });
+      const baseTitle = base[0].layers?.find((l) => l.id === 'title');
+      const slowedTitle = slowed[0].layers?.find((l) => l.id === 'title');
+      expect(slowedTitle?.animation?.duration).toBe((baseTitle?.animation?.duration ?? 0) * 2);
+    });
+
+    it('gives full-bleed imagery ambient Ken Burns when the theme opts in', () => {
+      const theme = {
+        ...DEFAULT_THEME,
+        renderStyle: { ...DEFAULT_THEME.renderStyle, ambientMotion: true },
+      };
+      const result = expandDocBlocks(blocks(), { theme });
+      const bg = result[1].layers?.find((l) => l.id === 'bg-image');
+      expect(bg?.animation?.type).toBe('slowZoom');
+      // Standard theme (ambientMotion: false) leaves the image static.
+      const plain = expandDocBlocks(blocks());
+      const plainBg = plain[1].layers?.find((l) => l.id === 'bg-image');
+      expect(plainBg?.animation).toBeUndefined();
+    });
+
+    it('themedEntrance: theme default text animation overrides entrance type, keeps timing', () => {
+      const theme = {
+        ...DEFAULT_THEME,
+        renderStyle: { ...DEFAULT_THEME.renderStyle, defaultTextAnimation: 'zoomIn' as const },
+      };
+      const result = expandDocBlocks(blocks(), { theme });
+      const title = result[0].layers?.find((l) => l.id === 'title');
+      expect(title?.animation?.type).toBe('zoomIn');
+      // Duration authored by the template is preserved (title uses 2s)
+      expect(title?.animation?.duration).toBe(2);
+    });
+
+    it('templateHints: dramatic entrance switches statHighlight timing', () => {
+      const statBlock: TemplateBlock[] = [
+        {
+          template: 'statHighlight',
+          id: 's-1',
+          duration: 5,
+          audioSegment: 0,
+          stat: '42%',
+          description: 'described',
+        },
+      ];
+      const theme = {
+        ...DEFAULT_THEME,
+        renderStyle: {
+          ...DEFAULT_THEME.renderStyle,
+          templateHints: { statHighlight: { entrance: 'dramatic' } },
+        },
+      };
+      const hinted = expandDocBlocks(statBlock, { theme });
+      const plain = expandDocBlocks(statBlock);
+      const hintedStat = hinted[0].layers?.find((l) => l.id === 'stat');
+      const plainStat = plain[0].layers?.find((l) => l.id === 'stat');
+      expect(hintedStat?.animation?.duration).toBe(0.4);
+      expect(plainStat?.animation?.duration).toBe(0.6);
+    });
+
+    it('theme persistentLayers render for docs without their own (wholesale precedence)', () => {
+      const theme = {
+        ...DEFAULT_THEME,
+        persistentLayers: {
+          bottomLayers: [
+            {
+              template: 'solidBackground' as const,
+              config: { type: 'solidBackground' as const, color: '#112233' },
+            },
+          ],
+        },
+      };
+      const inherited = expandDocBlocks(blocks(), { theme });
+      expect(inherited[0].layers?.[0]?.id).toContain('solid');
+
+      // Doc's own persistent layers win wholesale
+      const docOwn = expandDocBlocks(blocks(), {
+        theme,
+        persistentLayers: {
+          bottomLayers: [
+            {
+              template: 'solidBackground' as const,
+              config: { type: 'solidBackground' as const, color: '#445566' },
+            },
+          ],
+        },
+      });
+      const first = docOwn[0].layers?.[0];
+      expect(first && 'content' in first && (first.content as { fill?: string }).fill).toBe(
+        '#445566',
+      );
+    });
+  });
 });
 
 describe('DEFAULT_THEME', () => {
@@ -319,6 +533,45 @@ describe('DEFAULT_THEME', () => {
   });
 });
 
+describe('inline-param coercion → getLayers', () => {
+  function firstBlock(md: string) {
+    return markdownToDoc(parseMarkdown(md), { generateCoverBlock: false }).blocks[0];
+  }
+
+  it('renders a map from pure-inline {[map center=… zoom=…]} annotation', () => {
+    const block = firstBlock('# Downtown {[map center="47.6,-122.3" zoom=9 mapStyle="road"]}\n');
+    // Raw overrides stay strings for lossless round-trip.
+    expect(block.templateOverrides).toEqual({
+      center: '47.6,-122.3',
+      zoom: '9',
+      mapStyle: 'road',
+    });
+
+    const layers = getLayers(block, {});
+    const mapLayer = layers.find((l) => l.type === 'map');
+    expect(mapLayer).toBeDefined();
+    // Coerced center/zoom flow into the map layer's content — not empty strings.
+    const content = mapLayer!.content as { center: { lat: number; lng: number }; zoom: number };
+    expect(content.center).toEqual({ lat: 47.6, lng: -122.3 });
+    expect(content.zoom).toBe(9);
+  });
+
+  it('renders a twoColumn from pure-inline labeled-pair annotation', () => {
+    const block = firstBlock('# Coffee {[twoColumn left="Espresso|Bold" right="Filter|Smooth"]}\n');
+    const layers = getLayers(block, {});
+    // Guard requires both labels — a non-empty layer set proves coercion worked.
+    expect(layers.length).toBeGreaterThan(0);
+    const texts = layers
+      .filter((l) => l.type === 'text')
+      .map((l) => (l.content as { text: string }).text);
+    expect(texts).toContain('Espresso');
+    expect(texts).toContain('Filter');
+    // The sublabels from the "|" split render too.
+    expect(texts).toContain('Bold');
+    expect(texts).toContain('Smooth');
+  });
+});
+
 describe('VIEWPORT_PRESETS', () => {
   it('has landscape and portrait presets', () => {
     expect(VIEWPORT_PRESETS).toHaveProperty('landscape');

package/src/__tests__/themeCompile.test.ts

@@ -71,6 +71,48 @@ describe('compileTheme', () => {
   });
 });
 
+describe('compileTheme base inheritance', () => {
+  it('inherits renderStyle and colorSchemes from a chosen base', () => {
+    const base = resolveTheme('cinematic');
+    const theme = compileTheme(
+      { id: 'brand', name: 'Brand', seedColors: { primary: '#3182ce' } },
+      { base },
+    );
+    expect(theme.basedOn).toBe('cinematic');
+    // renderStyle inherited from the base (not the starter's 'standard')
+    expect(theme.renderStyle.name).toBe(base.renderStyle.name);
+    // colorSchemes inherited wholesale from the base
+    expect(theme.colorSchemes).toEqual(base.colorSchemes);
+    // ...but colors are still derived from the user's seed
+    expect(theme.colors.primary).toBe('#3182ce');
+  });
+
+  it('replaces colorSchemes wholesale when the partial supplies them (removal sticks)', () => {
+    const base = resolveTheme('cinematic');
+    const theme = compileTheme(
+      {
+        id: 'brand',
+        name: 'Brand',
+        seedColors: { primary: '#3182ce' },
+        colorSchemes: { onlyOne: { bg: '#111111', text: '#eeeeee', accent: '#3182ce' } },
+      },
+      { base },
+    );
+    // Only the scheme the user kept — the base's blue/green/… are gone.
+    expect(Object.keys(theme.colorSchemes)).toEqual(['onlyOne']);
+  });
+
+  it('defaults to the neutral starter when no base is given (basedOn unset)', () => {
+    const theme = compileTheme({
+      id: 'brand',
+      name: 'Brand',
+      seedColors: { primary: '#3182ce' },
+    });
+    expect(theme.basedOn).toBeUndefined();
+    expect(theme.renderStyle.name).toBe('standard');
+  });
+});
+
 describe('parseTheme / serializeTheme round-trip', () => {
   it('serialize → parse is lossless for built-ins', () => {
     for (const [id, theme] of Object.entries(THEMES)) {

package/src/__tests__/themeValidator.test.ts

@@ -105,6 +105,12 @@ describe('validateTheme', () => {
     expect(validateTheme(t).valid).toBe(true);
   });
 
+  it('accepts PowerPoint-style default transitions', () => {
+    const t = clone(DEFAULT_THEME);
+    t.renderStyle.defaultTransition = { type: 'checkerboard', duration: 1 };
+    expect(validateTheme(t).valid).toBe(true);
+  });
+
   it('rejects seedColors without primary', () => {
     const bad = clone(DEFAULT_THEME);
     bad.seedColors = { accent: '#63b3ed' } as never;

package/src/__tests__/transformV2.test.ts

@@ -0,0 +1,137 @@
+import { describe, it, expect, afterEach } from 'vitest';
+import {
+  applyTransform,
+  resolveTransformStyle,
+  registerTransformStyle,
+  unregisterTransformStyle,
+  getTransformStyleIds,
+} from '../transform/index.js';
+import type { TransformStyleConfig } from '../transform/index.js';
+import type { Doc, Block } from '../schemas/Doc.js';
+import { isTemplateBlock } from '../schemas/BlockTemplates.js';
+
+function paragraphBlock(id: string, title: string, text: string, duration = 20): Block {
+  return {
+    id,
+    startTime: 0,
+    duration,
+    audioSegment: 0,
+    title,
+    contents: [
+      {
+        type: 'paragraph',
+        children: [{ type: 'text', value: text }],
+      },
+    ],
+  };
+}
+
+/** Body with a strong quote extraction. */
+const QUOTED =
+  'The ranger paused at the overlook. "The mountain decides who climbs it," she said quietly. ' +
+  'Every year thousands of visitors make the same journey up the winding road to Paradise.';
+
+function sampleDoc(): Doc {
+  return {
+    articleId: 'transform-v2-test',
+    duration: 60,
+    blocks: [
+      paragraphBlock('b1', 'The Mountain', QUOTED),
+      paragraphBlock(
+        'b2',
+        'Visitors',
+        'In 2024 the park recorded 2.5 million visitors, a 40% increase over the prior decade. ' +
+          'Rangers attribute the growth to social media and improved road access.',
+      ),
+    ],
+    audio: { segments: [] },
+  };
+}
+
+describe('transform style contract v2', () => {
+  afterEach(() => unregisterTransformStyle('custom-test'));
+
+  it('suggestedThemeId applies only when the doc declares no theme', () => {
+    const { doc } = applyTransform(sampleDoc(), 'magazine');
+    expect(doc.themeId).toBe('magazine');
+
+    const themed = { ...sampleDoc(), themeId: 'gezellig' };
+    expect(applyTransform(themed, 'magazine').doc.themeId).toBe('gezellig');
+
+    const viaOption = applyTransform(sampleDoc(), 'magazine', { themeId: 'bold' });
+    expect(viaOption.doc.themeId).toBe('bold');
+  });
+
+  it('templateMap remaps quote extractions (magazine → pullQuote with accent image as background)', () => {
+    const images = [{ src: 'photo.jpg', alt: 'a photo' }];
+    const { doc } = applyTransform(sampleDoc(), 'magazine', { images });
+    const templates = doc.blocks.filter(isTemplateBlock).map((b) => b.template);
+    // The quote extraction maps to pullQuote (magazine's templateMap)
+    // because an image was available to serve as the background.
+    expect(templates).toContain('pullQuote');
+    expect(templates).not.toContain('quote');
+  });
+
+  it('templateMap remap falls back to the default when the target needs an unavailable image', () => {
+    const { doc } = applyTransform(sampleDoc(), 'magazine', { images: [] });
+    const templates = doc.blocks.filter(isTemplateBlock).map((b) => b.template);
+    expect(templates).toContain('quote');
+    expect(templates).not.toContain('pullQuote');
+  });
+
+  it('pacing adds intro/outro bookends (narrative)', () => {
+    const { doc } = applyTransform(sampleDoc(), 'narrative');
+    const first = doc.blocks[0];
+    const last = doc.blocks[doc.blocks.length - 1];
+    expect(first.template).toBe('title');
+    expect(first.title ?? (first as { title?: string }).title).toBeDefined();
+    expect(last.template).toBe('sectionHeader');
+  });
+
+  it('registerTransformStyle adds a resolvable style that wins over unknown fallback', () => {
+    const custom: TransformStyleConfig = {
+      ...resolveTransformStyle('minimal'),
+      id: 'custom-test',
+      name: 'Custom Test',
+      description: 'test style',
+    };
+    registerTransformStyle(custom);
+    expect(getTransformStyleIds()).toContain('custom-test');
+    expect(resolveTransformStyle('custom-test').name).toBe('Custom Test');
+    unregisterTransformStyle('custom-test');
+    // Unknown id falls back to the default (documentary)
+    expect(resolveTransformStyle('custom-test').id).toBe('documentary');
+  });
+
+  it("accepts 'dataDriven' as an alias for the hyphenated registry id", () => {
+    expect(resolveTransformStyle('dataDriven').id).toBe('data-driven');
+  });
+
+  it('budget.slidesPerMinute caps promotions on long docs', () => {
+    const manyBlocks: Doc = {
+      articleId: 'budget-test',
+      duration: 60,
+      blocks: Array.from({ length: 12 }, (_, i) =>
+        paragraphBlock(
+          `b${i}`,
+          `Section ${i}`,
+          `In 2024 the park recorded ${(i + 2) * 7}% growth across all visitor categories nationwide.`,
+          5,
+        ),
+      ),
+      audio: { segments: [] },
+    };
+    const unbudgeted = resolveTransformStyle('data-driven');
+    const budgeted: TransformStyleConfig = {
+      ...unbudgeted,
+      id: 'custom-test',
+      budget: { slidesPerMinute: 2 },
+    };
+    registerTransformStyle(budgeted);
+    const loose = applyTransform(manyBlocks, 'data-driven');
+    const tight = applyTransform(manyBlocks, 'custom-test');
+    expect(tight.stats.transformedBlocks).toBeLessThan(loose.stats.transformedBlocks);
+    // 12 blocks x 5s = 60s → 2/minute → at most 2 promotions
+    expect(tight.stats.transformedBlocks).toBeLessThanOrEqual(2);
+  });
+});

package/src/__tests__/transitionNormalize.test.ts

@@ -0,0 +1,61 @@
+import { describe, it, expect } from 'vitest';
+import {
+  normalizeTransitionType,
+  normalizeTransitionDirection,
+  isTransitionType,
+  TRANSITION_TYPES,
+} from '../schemas/Transitions';
+
+describe('normalizeTransitionType', () => {
+  it('returns exact canonical types unchanged', () => {
+    expect(normalizeTransitionType('fade')).toBe('fade');
+    expect(normalizeTransitionType('checkerboard')).toBe('checkerboard');
+    expect(normalizeTransitionType('slideLeft')).toBe('slideLeft');
+  });
+
+  it('resolves case / punctuation variants of canonical types', () => {
+    // These have NO explicit alias entry — they round-trip through the
+    // case-insensitive `NORMALIZED_TRANSITION_TYPES` fallback. This guards the
+    // removal of the redundant self-aliases (checkerboard/shape/uncover).
+    expect(normalizeTransitionType('Checkerboard')).toBe('checkerboard');
+    expect(normalizeTransitionType('CHECKERBOARD')).toBe('checkerboard');
+    expect(normalizeTransitionType('Shape')).toBe('shape');
+    expect(normalizeTransitionType('Uncover')).toBe('uncover');
+    expect(normalizeTransitionType('fly-through')).toBe('flyThrough');
+  });
+
+  it('resolves explicit aliases (including plurals)', () => {
+    // Aliases only fire for spellings that are NOT themselves canonical types
+    // (an exact type returns early). `ferris` IS a canonical type, so its
+    // sameness with `ferrisWheel` comes from the visual map, not here.
+    expect(normalizeTransitionType('none')).toBe('cut');
+    expect(normalizeTransitionType('checkerboards')).toBe('checkerboard');
+    expect(normalizeTransitionType('shapes')).toBe('shape');
+    expect(normalizeTransitionType('flythru')).toBe('flyThrough');
+  });
+
+  it('returns null for unknown values', () => {
+    expect(normalizeTransitionType('definitely-not-a-transition')).toBeNull();
+    expect(normalizeTransitionType('')).toBeNull();
+  });
+
+  it('every canonical type normalizes to itself', () => {
+    for (const type of TRANSITION_TYPES) {
+      expect(normalizeTransitionType(type), type).toBe(type);
+      expect(isTransitionType(type), type).toBe(true);
+    }
+  });
+});
+
+describe('normalizeTransitionDirection', () => {
+  it('resolves cardinal directions and shorthands', () => {
+    expect(normalizeTransitionDirection('left')).toBe('left');
+    expect(normalizeTransitionDirection('R')).toBe('right');
+    expect(normalizeTransitionDirection('horizontal')).toBe('horizontal');
+    expect(normalizeTransitionDirection('v')).toBe('vertical');
+  });
+
+  it('returns null for unknown directions', () => {
+    expect(normalizeTransitionDirection('sideways')).toBeNull();
+  });
+});