@bendyline/squisq 1.2.2 → 1.4.0

package/src/__tests__/templateAnnotationParse.test.ts

@@ -0,0 +1,42 @@
+import { describe, it, expect } from 'vitest';
+import { parseMarkdown } from '../markdown/parse.js';
+import { markdownToDoc } from '../doc/markdownToDoc.js';
+
+describe('Template annotation in Heading parse path', () => {
+  it('parseMarkdown extracts {[template]} from a heading', () => {
+    const md = '## Getting Started {[comparisonBar]}';
+    const doc = parseMarkdown(md);
+    const heading = doc.children[0];
+    expect(heading.type).toBe('heading');
+    if (heading.type !== 'heading') return;
+    expect(heading.templateAnnotation).toEqual({ template: 'comparisonBar' });
+  });
+
+  it('markdownToDoc preserves templateAnnotation on the resulting block', () => {
+    const md = '# Title\n\n## Getting Started {[comparisonBar]}\n\nBody.';
+    const parsed = parseMarkdown(md);
+    const doc = markdownToDoc(parsed, { articleId: 'test' });
+    // The h1 is the root; first child is the h2 with annotation
+    const h1 = doc.blocks[0];
+    expect(h1.sourceHeading?.depth).toBe(1);
+    const h2 = h1.children?.[0];
+    expect(h2?.sourceHeading?.depth).toBe(2);
+    expect(h2?.sourceHeading?.templateAnnotation).toEqual({ template: 'comparisonBar' });
+  });
+
+  it('tolerates accidentally-doubled trailing `]}` (user typo)', () => {
+    const md = '## Getting Started {[comparisonBar]}]}';
+    const doc = parseMarkdown(md);
+    const heading = doc.children[0];
+    if (heading.type !== 'heading') throw new Error('expected heading');
+    expect(heading.templateAnnotation).toEqual({ template: 'comparisonBar' });
+  });
+
+  it('still rejects non-trailing annotations (regex stays anchored)', () => {
+    const md = '## The {[chart]} section'; // word continues after — not an annotation
+    const doc = parseMarkdown(md);
+    const heading = doc.children[0];
+    if (heading.type !== 'heading') throw new Error('expected heading');
+    expect(heading.templateAnnotation).toBeUndefined();
+  });
+});

package/src/__tests__/templates.test.ts

@@ -14,17 +14,19 @@ import type { TemplateBlock } from '../schemas/BlockTemplates';
 describe('templateRegistry', () => {
   it('contains all expected templates', () => {
     const expected = [
-      'titleBlock',
+      'title',
       'sectionHeader',
       'statHighlight',
-      'quoteBlock',
+      'quote',
       'factCard',
       'twoColumn',
       'dateEvent',
       'imageWithCaption',
-      'mapBlock',
+      'leftFeature',
+      'rightFeature',
+      'map',
       'fullBleedQuote',
-      'listBlock',
+      'list',
       'photoGrid',
       'definitionCard',
       'comparisonBar',
@@ -43,7 +45,7 @@ describe('templateRegistry', () => {
 describe('getAvailableTemplates', () => {
   it('returns array of template names', () => {
     const templates = getAvailableTemplates();
-    expect(templates).toContain('titleBlock');
+    expect(templates).toContain('title');
     expect(templates).toContain('sectionHeader');
     expect(templates.length).toBeGreaterThanOrEqual(15);
   });
@@ -51,7 +53,7 @@ describe('getAvailableTemplates', () => {
 
 describe('hasTemplate', () => {
   it('returns true for existing templates', () => {
-    expect(hasTemplate('titleBlock')).toBe(true);
+    expect(hasTemplate('title')).toBe(true);
     expect(hasTemplate('statHighlight')).toBe(true);
   });
 
@@ -63,7 +65,7 @@ describe('hasTemplate', () => {
 describe('expandTemplateBlock', () => {
   it('expands titleSlide template into layers', () => {
     const block: TemplateBlock = {
-      template: 'titleBlock',
+      template: 'title',
       id: 'title-1',
       duration: 10,
       audioSegment: 0,
@@ -79,6 +81,88 @@ describe('expandTemplateBlock', () => {
     expect((result.layers ?? []).length).toBeGreaterThan(0);
   });
 
+  it('expands leftFeature template with image on the left half and left-aligned text right', () => {
+    const block: TemplateBlock = {
+      template: 'leftFeature',
+      id: 'lf-1',
+      duration: 6,
+      audioSegment: 0,
+      imageSrc: 'hero.jpg',
+      imageAlt: 'hero',
+      title: 'Product Builder',
+      body: 'I love building software platforms.',
+    };
+    const context = createTemplateContext(DEFAULT_THEME, 0, 1, VIEWPORT_PRESETS.landscape);
+    const result = expandTemplateBlock(block, context);
+    const layers = result.layers ?? [];
+    const imageLayer = layers.find((l) => l.type === 'image');
+    expect(imageLayer).toBeDefined();
+    expect(imageLayer!.position.x).toBe('0');
+    expect(imageLayer!.position.width).toBe('50%');
+    // Text column sits just past the 50% divider, top-left anchored,
+    // so the title and body share a left edge with comfortable padding.
+    const textLayers = layers.filter((l) => l.type === 'text');
+    expect(textLayers.length).toBeGreaterThanOrEqual(1);
+    for (const t of textLayers) {
+      expect(t.position.x).toBe('54%');
+      expect(t.position.anchor).toBe('top-left');
+      expect((t.content as { style: { textAlign?: string } }).style.textAlign).toBe('left');
+    }
+  });
+
+  it('respects explicit image dimensions: contained + padded inside the half', () => {
+    // When the user resizes an image in the WYSIWYG editor it round-
+    // trips as `<img width …>`. Feature blocks should treat that as a
+    // hint to NOT stretch the image — render it centered with padding
+    // around it.
+    const block: TemplateBlock = {
+      template: 'leftFeature',
+      id: 'lf-sized',
+      duration: 6,
+      audioSegment: 0,
+      imageSrc: 'hero.jpg',
+      imageAlt: 'hero',
+      imageWidth: 194,
+      title: 'Sized',
+    };
+    const context = createTemplateContext(DEFAULT_THEME, 0, 1, VIEWPORT_PRESETS.landscape);
+    const result = expandTemplateBlock(block, context);
+    const imageLayer = (result.layers ?? []).find((l) => l.type === 'image');
+    expect(imageLayer).toBeDefined();
+    expect((imageLayer!.content as { fit?: string }).fit).toBe('contain');
+    // Image is inset from the half's edges rather than filling them.
+    expect(imageLayer!.position.x).toBe('5%');
+    expect(imageLayer!.position.width).toBe('40%');
+    expect(imageLayer!.position.y).toBe('5%');
+    expect(imageLayer!.position.height).toBe('90%');
+  });
+
+  it('expands rightFeature template with image on the right half and right-aligned text left', () => {
+    const block: TemplateBlock = {
+      template: 'rightFeature',
+      id: 'rf-1',
+      duration: 6,
+      audioSegment: 0,
+      imageSrc: 'hero.jpg',
+      imageAlt: 'hero',
+      title: 'Projects',
+      body: 'A list of things.',
+    };
+    const context = createTemplateContext(DEFAULT_THEME, 0, 1, VIEWPORT_PRESETS.landscape);
+    const result = expandTemplateBlock(block, context);
+    const layers = result.layers ?? [];
+    const imageLayer = layers.find((l) => l.type === 'image');
+    expect(imageLayer).toBeDefined();
+    expect(imageLayer!.position.x).toBe('50%');
+    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');
+    }
+  });
+
   it('expands statHighlight template', () => {
     const block: TemplateBlock = {
       template: 'statHighlight',
@@ -163,7 +247,7 @@ describe('expandTemplateBlock', () => {
 describe('expandDocBlocks', () => {
   it('expands array of template blocks with cumulative timing', () => {
     const blocks: TemplateBlock[] = [
-      { template: 'titleBlock', id: 'slide-1', duration: 5, audioSegment: 0, title: 'Hello' },
+      { template: 'title', id: 'slide-1', duration: 5, audioSegment: 0, title: 'Hello' },
       {
         template: 'factCard',
         id: 'slide-2',
@@ -213,7 +297,7 @@ describe('expandDocBlocks', () => {
 
   it('supports landscape and portrait viewports', () => {
     const blocks: TemplateBlock[] = [
-      { template: 'titleBlock', id: 'title-1', duration: 5, audioSegment: 0, title: 'Test' },
+      { template: 'title', id: 'title-1', duration: 5, audioSegment: 0, title: 'Test' },
     ];
 
     const landscape = expandDocBlocks(blocks, { viewport: VIEWPORT_PRESETS.landscape });

package/src/__tests__/themeCompile.test.ts

@@ -0,0 +1,156 @@
+import { describe, it, expect } from 'vitest';
+import {
+  compileTheme,
+  parseTheme,
+  serializeTheme,
+  STARTER_THEME,
+  deriveColorPalette,
+} from '../schemas/themeCompile.js';
+import { registerTheme, unregisterTheme, getRegisteredThemes } from '../schemas/Theme.js';
+import { resolveTheme, DEFAULT_THEME, THEMES } from '../schemas/themeLibrary.js';
+import { resolveFontFamily } from '../schemas/fontStacks.js';
+
+describe('deriveColorPalette', () => {
+  it('fills all 8 palette slots from a single primary seed', () => {
+    const palette = deriveColorPalette({ primary: '#3182ce' });
+    expect(palette.primary).toBe('#3182ce');
+    expect(palette.background).toMatch(/^#[0-9a-f]{6}$/);
+    expect(palette.text).toMatch(/^#[0-9a-f]{6}$/);
+    expect(palette.warning).toMatch(/^#[0-9a-f]{6}$/);
+  });
+
+  it('lets explicit partial colors win over derived values', () => {
+    const palette = deriveColorPalette({ primary: '#3182ce' }, { warning: '#ff00ff' });
+    expect(palette.warning).toBe('#ff00ff');
+  });
+
+  it('high contrast spread > balanced spread > subtle spread (in lightness range)', () => {
+    const subtle = deriveColorPalette({ primary: '#3182ce' }, {}, { contrast: 'subtle' });
+    const balanced = deriveColorPalette({ primary: '#3182ce' }, {}, { contrast: 'balanced' });
+    const high = deriveColorPalette({ primary: '#3182ce' }, {}, { contrast: 'high' });
+    // All should be valid
+    for (const p of [subtle, balanced, high]) {
+      expect(p.background).toMatch(/^#[0-9a-f]{6}$/);
+    }
+  });
+});
+
+describe('compileTheme', () => {
+  it('compiles a minimal partial into a complete validated Theme', () => {
+    const theme = compileTheme({
+      name: 'My Theme',
+      seedColors: { primary: '#3182ce' },
+    });
+    expect(theme.id).toMatch(/^custom/);
+    expect(theme.name).toBe('My Theme');
+    expect(theme.colors.primary).toBe('#3182ce');
+    expect(theme.colors.background).toMatch(/^#[0-9a-f]{6}$/);
+    expect(theme.typography.bodyFont).toEqual(STARTER_THEME.typography.bodyFont);
+    expect(theme.colorSchemes).toEqual(STARTER_THEME.colorSchemes);
+    expect(theme.schemaVersion).toBe('1');
+  });
+
+  it('passes through fully-specified themes (built-ins should re-compile to identical Theme)', () => {
+    const reCompiled = compileTheme(DEFAULT_THEME);
+    expect(reCompiled.colors).toEqual(DEFAULT_THEME.colors);
+    expect(reCompiled.typography).toEqual(DEFAULT_THEME.typography);
+  });
+
+  it('honors typography overrides', () => {
+    const theme = compileTheme({
+      seedColors: { primary: '#3182ce' },
+      typography: {
+        titleFont: { stackId: 'playfair' },
+        bodyFont: { custom: { name: 'Georgia', fallback: 'serif' } },
+      },
+    });
+    expect(theme.typography.titleFont).toEqual({ stackId: 'playfair' });
+    expect(theme.typography.bodyFont).toEqual({
+      custom: { name: 'Georgia', fallback: 'serif' },
+    });
+  });
+});
+
+describe('parseTheme / serializeTheme round-trip', () => {
+  it('serialize → parse is lossless for built-ins', () => {
+    for (const [id, theme] of Object.entries(THEMES)) {
+      const json = serializeTheme(theme);
+      const parsed = parseTheme(json);
+      expect(parsed).toEqual(theme);
+      expect(parsed.id).toBe(id);
+    }
+  });
+
+  it('parseTheme throws on invalid JSON', () => {
+    expect(() => parseTheme('not json')).toThrow(/Invalid theme JSON/);
+  });
+
+  it('parseTheme throws on JSON that fails validation', () => {
+    expect(() => parseTheme('{}')).toThrow(/Invalid parsed theme/);
+  });
+});
+
+describe('registerTheme / resolveTheme', () => {
+  it('registered theme takes precedence over built-in with same id', () => {
+    const overlay = compileTheme({
+      id: 'standard',
+      name: 'Standard Override',
+      seedColors: { primary: '#ff0000' },
+    });
+    registerTheme(overlay);
+    try {
+      const resolved = resolveTheme('standard');
+      expect(resolved.name).toBe('Standard Override');
+      expect(resolved.colors.primary).toBe('#ff0000');
+    } finally {
+      unregisterTheme('standard');
+    }
+    // After cleanup, built-in is restored
+    expect(resolveTheme('standard').name).toBe('Standard Light');
+  });
+
+  it('registered custom-id theme is resolvable via Doc.themeId', () => {
+    const custom = compileTheme({
+      id: 'custom-test-1',
+      name: 'Custom Test One',
+      seedColors: { primary: '#00aabb' },
+    });
+    registerTheme(custom);
+    try {
+      const resolved = resolveTheme('custom-test-1');
+      expect(resolved.id).toBe('custom-test-1');
+      expect(resolved.name).toBe('Custom Test One');
+      expect(getRegisteredThemes().some((t) => t.id === 'custom-test-1')).toBe(true);
+    } finally {
+      unregisterTheme('custom-test-1');
+    }
+  });
+
+  it('resolveTheme falls back to default for unknown ids', () => {
+    expect(resolveTheme('nonexistent-theme')).toBe(DEFAULT_THEME);
+    expect(resolveTheme(undefined)).toBe(DEFAULT_THEME);
+  });
+});
+
+describe('FontFamily resolution', () => {
+  it('resolves stackId to a CSS family string', () => {
+    expect(resolveFontFamily({ stackId: 'inter' }, 'fallback')).toContain('Inter');
+  });
+
+  it('resolves { custom } to a quoted CSS family with fallback', () => {
+    const css = resolveFontFamily(
+      { custom: { name: 'My Font', fallback: 'sans-serif' } },
+      'fallback',
+    );
+    expect(css).toContain('"My Font"');
+    expect(css).toContain('sans-serif');
+  });
+
+  it('returns roleFallback for unknown stackId', () => {
+    expect(resolveFontFamily({ stackId: 'no-such-stack' }, 'my-fallback')).toBe('my-fallback');
+  });
+
+  it('accepts legacy raw strings for backward compat', () => {
+    expect(resolveFontFamily('Georgia, serif', 'fallback')).toBe('Georgia, serif');
+  });
+});

package/src/__tests__/themeValidator.test.ts

@@ -0,0 +1,125 @@
+import { describe, it, expect } from 'vitest';
+import { validateTheme, assertTheme } from '../schemas/themeValidator.js';
+import { THEMES, DEFAULT_THEME } from '../schemas/themeLibrary.js';
+import type { Theme } from '../schemas/Theme.js';
+
+function clone<T>(v: T): T {
+  return JSON.parse(JSON.stringify(v)) as T;
+}
+
+describe('validateTheme', () => {
+  it('accepts every built-in theme', () => {
+    for (const [id, theme] of Object.entries(THEMES)) {
+      const result = validateTheme(theme);
+      if (!result.valid) {
+        throw new Error(
+          `Built-in theme "${id}" failed validation:\n${result.errors
+            .map((e) => `  ${e.path}: ${e.message}`)
+            .join('\n')}`,
+        );
+      }
+      expect(result.valid).toBe(true);
+    }
+  });
+
+  it('rejects non-objects', () => {
+    expect(validateTheme(null).valid).toBe(false);
+    expect(validateTheme('a string').valid).toBe(false);
+    expect(validateTheme(42).valid).toBe(false);
+  });
+
+  it('flags missing required fields', () => {
+    const result = validateTheme({ schemaVersion: '1', id: 'x', name: 'X' });
+    expect(result.valid).toBe(false);
+    const paths = result.errors.map((e) => e.path);
+    expect(paths).toContain('colors');
+    expect(paths).toContain('typography');
+    expect(paths).toContain('renderStyle');
+    expect(paths).toContain('colorSchemes');
+  });
+
+  it('flags raw font strings (legacy shape)', () => {
+    const bad = clone(DEFAULT_THEME) as unknown as Record<string, unknown>;
+    (bad.typography as Record<string, unknown>).bodyFont = 'Inter, sans-serif';
+    const result = validateTheme(bad);
+    expect(result.valid).toBe(false);
+    expect(result.errors.some((e) => e.path === 'typography.bodyFont')).toBe(true);
+  });
+
+  it('flags raw CSS gradient strings in persistentLayers', () => {
+    const bad = clone(DEFAULT_THEME) as Theme;
+    bad.persistentLayers = {
+      bottomLayers: [
+        // intentionally invalid: raw `gradient` string is not allowed
+        {
+          template: 'gradientBackground',
+          config: {
+            type: 'gradientBackground',
+            gradient: 'linear-gradient(...)' as never,
+          },
+        },
+      ],
+    };
+    const result = validateTheme(bad);
+    expect(result.valid).toBe(false);
+    expect(
+      result.errors.some((e) => e.path.endsWith('config.gradient') && /raw CSS/i.test(e.message)),
+    ).toBe(true);
+  });
+
+  it('flags malformed hex colors', () => {
+    const bad = clone(DEFAULT_THEME);
+    bad.colors.primary = 'rgb(0,0,0)';
+    const result = validateTheme(bad);
+    expect(result.valid).toBe(false);
+    expect(result.errors.some((e) => e.path === 'colors.primary')).toBe(true);
+  });
+
+  it('flags wrong schemaVersion', () => {
+    const bad = clone(DEFAULT_THEME) as unknown as Record<string, unknown>;
+    bad.schemaVersion = '2';
+    const result = validateTheme(bad);
+    expect(result.valid).toBe(false);
+    expect(result.errors.some((e) => e.path === 'schemaVersion')).toBe(true);
+  });
+
+  it('accepts FontFamily { custom } shape', () => {
+    const t = clone(DEFAULT_THEME);
+    t.typography.bodyFont = { custom: { name: 'Georgia', fallback: 'serif' } };
+    expect(validateTheme(t).valid).toBe(true);
+  });
+
+  it('rejects FontFamily.custom with bad fallback', () => {
+    const bad = clone(DEFAULT_THEME) as unknown as Record<string, unknown>;
+    (bad.typography as Record<string, unknown>).bodyFont = {
+      custom: { name: 'Georgia', fallback: 'invalid' },
+    };
+    const result = validateTheme(bad);
+    expect(result.valid).toBe(false);
+    expect(result.errors.some((e) => e.path === 'typography.bodyFont.custom.fallback')).toBe(true);
+  });
+
+  it('accepts theme with seedColors', () => {
+    const t = clone(DEFAULT_THEME);
+    t.seedColors = { primary: '#3182ce', accent: '#63b3ed' };
+    expect(validateTheme(t).valid).toBe(true);
+  });
+
+  it('rejects seedColors without primary', () => {
+    const bad = clone(DEFAULT_THEME);
+    bad.seedColors = { accent: '#63b3ed' } as never;
+    const result = validateTheme(bad);
+    expect(result.valid).toBe(false);
+    expect(result.errors.some((e) => e.path === 'seedColors.primary')).toBe(true);
+  });
+});
+
+describe('assertTheme', () => {
+  it('returns the theme unchanged when valid', () => {
+    expect(assertTheme(DEFAULT_THEME)).toBe(DEFAULT_THEME);
+  });
+
+  it('throws with a readable error summary on invalid input', () => {
+    expect(() => assertTheme({}, 'test theme')).toThrow(/Invalid test theme/);
+  });
+});