@bendyline/squisq 1.4.0 → 1.5.0

package/src/__tests__/templates.test.ts

@@ -137,7 +137,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 +157,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');
     }
   });
 
@@ -309,6 +311,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', () => {

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();
+  });
+});

package/src/__tests__/validateDoc.test.ts

@@ -0,0 +1,100 @@
+import { describe, it, expect } from 'vitest';
+import { validateMarkdownSource } from '../doc/validate.js';
+
+function codes(md: string, options?: Parameters<typeof validateMarkdownSource>[1]): string[] {
+  return validateMarkdownSource(md, options).diagnostics.map((d) => d.code);
+}
+
+describe('validateMarkdownSource — templates', () => {
+  it('passes a clean document', () => {
+    const result = validateMarkdownSource('# Title\n\nBody.\n\n## Section {[quote]}\n\nA quote.\n');
+    expect(result.diagnostics).toEqual([]);
+    expect(result.errorCount).toBe(0);
+    expect(result.warningCount).toBe(0);
+  });
+
+  it('flags unknown templates with a did-you-mean suggestion', () => {
+    const result = validateMarkdownSource('## Gallery {[photGrid columns=3]}');
+    expect(result.warningCount).toBe(1);
+    const d = result.diagnostics[0];
+    expect(d.code).toBe('unknown-template');
+    expect(d.message).toContain('photGrid');
+    expect(d.message).toContain('Did you mean "photoGrid"?');
+    expect(d.line).toBe(1);
+  });
+
+  it('accepts legacy template aliases', () => {
+    expect(codes('## X {[titleBlock]}')).toEqual([]);
+  });
+
+  it('accepts extra templates supplied by the host app', () => {
+    expect(codes('## X {[hero]}', { extraTemplates: ['hero'] })).toEqual([]);
+    expect(codes('## X {[hero]}')).toEqual(['unknown-template']);
+  });
+});
+
+describe('validateMarkdownSource — unparsed annotations', () => {
+  it('flags {[…]} text in body content (annotations are heading-only)', () => {
+    const result = validateMarkdownSource('## X\n\n- {[imageWithCaption src=photo.jpg]}\n');
+    const d = result.diagnostics.find((x) => x.code === 'unparsed-annotation');
+    expect(d).toBeDefined();
+    expect(d!.message).toContain('headings');
+    expect(d!.line).toBe(3);
+  });
+
+  it('flags non-trailing {[…]} text left in a heading', () => {
+    const result = validateMarkdownSource('## The {[chart]} section\n');
+    expect(result.diagnostics.map((d) => d.code)).toContain('unparsed-annotation');
+  });
+
+  it('does not flag resolved inline icons or code blocks', () => {
+    const md = '## X\n\nUse {[github]} for code.\n\n```\nliteral {[notathing]}\n```\n';
+    expect(codes(md)).toEqual([]);
+  });
+});
+
+describe('validateMarkdownSource — attributes and structure', () => {
+  it('surfaces malformed heading-attribute values', () => {
+    const result = validateMarkdownSource('## X {#a x=abc}');
+    const d = result.diagnostics.find((x) => x.code === 'invalid-attribute');
+    expect(d).toBeDefined();
+    expect(d!.message).toContain('x');
+  });
+
+  it('includes conversion diagnostics (duplicate ids, bad fences)', () => {
+    const md = '## A {#dup}\n\n## B {#dup}\n\n```json data\nnot json\n```\n';
+    const result = validateMarkdownSource(md);
+    const found = result.diagnostics.map((d) => d.code);
+    expect(found).toContain('duplicate-id');
+    expect(found).toContain('data-fence-parse');
+    expect(result.errorCount).toBe(2);
+  });
+});
+
+describe('validateMarkdownSource — assets', () => {
+  it('flags relative image references missing from the asset set', () => {
+    const result = validateMarkdownSource('## X\n\n![hero](images/hero.jpg)\n', {
+      assets: new Set<string>(),
+    });
+    const d = result.diagnostics.find((x) => x.code === 'missing-asset');
+    expect(d).toBeDefined();
+    expect(d!.message).toContain('images/hero.jpg');
+  });
+
+  it('passes when the asset exists, and skips absolute/external URLs', () => {
+    const md =
+      '## X\n\n![a](images/hero.jpg)\n\n![b](https://example.com/x.jpg)\n\n![c](data:image/png;base64,AA==)\n';
+    expect(codes(md, { assets: new Set(['images/hero.jpg']) })).toEqual([]);
+  });
+
+  it('checks media params from {[…]} annotations', () => {
+    const result = validateMarkdownSource('## X {[imageWithCaption src=missing.png]}', {
+      assets: new Set<string>(),
+    });
+    expect(result.diagnostics.map((d) => d.code)).toContain('missing-asset');
+  });
+
+  it('skips asset checks entirely when no asset set is provided', () => {
+    expect(codes('## X\n\n![hero](images/hero.jpg)\n')).toEqual([]);
+  });
+});