@bendyline/squisq 1.4.0 → 1.5.0

package/src/doc/templates/tokens/__tests__/resolveTokens.test.ts

@@ -0,0 +1,221 @@
+/**
+ * resolveTokens — placeholder substitution unit tests.
+ *
+ * Covers each supported token, the escape syntax, and the edge cases
+ * called out in the plan (missing data, out-of-range image index,
+ * unknown token left literal).
+ */
+
+import { describe, it, expect } from 'vitest';
+import { resolveTokens } from '../resolveTokens';
+import type { Block, TextLayer, ImageLayer } from '../../../../schemas/Doc.js';
+
+function textLayer(id: string, text: string): TextLayer {
+  return {
+    id,
+    type: 'text',
+    position: { x: 0, y: 0, width: 100, height: 50 },
+    content: { text, style: { fontSize: 24, color: '#000' } },
+  };
+}
+
+function imageLayer(id: string, src: string, alt = ''): ImageLayer {
+  return {
+    id,
+    type: 'image',
+    position: { x: 0, y: 0, width: 100, height: 100 },
+    content: { src, alt },
+  };
+}
+
+function block(overrides: Partial<Block> = {}): Block {
+  return {
+    id: 'b',
+    startTime: 0,
+    duration: 1,
+    audioSegment: 0,
+    title: 'Block title',
+    ...overrides,
+  };
+}
+
+describe('resolveTokens — TextLayer', () => {
+  it('substitutes {title} with block.title', () => {
+    const layers = resolveTokens([textLayer('a', 'Hello, {title}!')], block({ title: 'World' }));
+    const out = layers[0] as TextLayer;
+    expect(out.content.text).toBe('Hello, World!');
+  });
+
+  it('collapses {title} to empty when block has no title', () => {
+    const layers = resolveTokens([textLayer('a', '[{title}]')], block({ title: undefined }));
+    expect((layers[0] as TextLayer).content.text).toBe('[]');
+  });
+
+  it('substitutes {content} from block.contents (plain text of body)', () => {
+    const layers = resolveTokens(
+      [textLayer('a', 'Body: {content}')],
+      block({
+        contents: [
+          {
+            type: 'paragraph',
+            children: [{ type: 'text', value: 'Hello there' }],
+          },
+        ],
+      }),
+    );
+    expect((layers[0] as TextLayer).content.text).toBe('Body: Hello there');
+  });
+
+  it('joins multiple paragraphs in {content} with single spaces', () => {
+    const layers = resolveTokens(
+      [textLayer('a', '{content}')],
+      block({
+        contents: [
+          { type: 'paragraph', children: [{ type: 'text', value: 'First.' }] },
+          { type: 'paragraph', children: [{ type: 'text', value: 'Second.' }] },
+        ],
+      }),
+    );
+    expect((layers[0] as TextLayer).content.text).toBe('First. Second.');
+  });
+
+  it('joins child titles for {children}', () => {
+    const layers = resolveTokens(
+      [textLayer('a', 'Sections: {children}')],
+      block({
+        children: [
+          block({ id: 'c1', title: 'Alpha' }),
+          block({ id: 'c2', title: 'Beta' }),
+          block({ id: 'c3', title: 'Gamma' }),
+        ],
+      }),
+    );
+    expect((layers[0] as TextLayer).content.text).toBe('Sections: Alpha, Beta, Gamma');
+  });
+
+  it('substitutes {image:N} with the Nth image alt text', () => {
+    const layers = resolveTokens(
+      [textLayer('a', 'Caption: {image:0}')],
+      block({
+        contents: [
+          {
+            type: 'paragraph',
+            children: [{ type: 'image', url: '/a.png', alt: 'Alpha image' }],
+          },
+        ],
+      }),
+    );
+    expect((layers[0] as TextLayer).content.text).toBe('Caption: Alpha image');
+  });
+
+  it('preserves {{title}} as literal {title}', () => {
+    const layers = resolveTokens(
+      [textLayer('a', 'Use {{title}} as a token, or {title} to expand')],
+      block({ title: 'My Doc' }),
+    );
+    expect((layers[0] as TextLayer).content.text).toBe(
+      'Use {title} as a token, or My Doc to expand',
+    );
+  });
+
+  it('leaves unknown tokens literal', () => {
+    const layers = resolveTokens([textLayer('a', 'Hello {nope} world')], block());
+    expect((layers[0] as TextLayer).content.text).toBe('Hello {nope} world');
+  });
+
+  it('substitutes multiple tokens in a single string', () => {
+    const layers = resolveTokens(
+      [textLayer('a', '{title} — {content}')],
+      block({
+        title: 'Doc',
+        contents: [{ type: 'paragraph', children: [{ type: 'text', value: 'body' }] }],
+      }),
+    );
+    expect((layers[0] as TextLayer).content.text).toBe('Doc — body');
+  });
+});
+
+describe('resolveTokens — ImageLayer', () => {
+  it('substitutes {image:0} with the Nth image URL in src', () => {
+    const layers = resolveTokens(
+      [imageLayer('a', '{image:0}')],
+      block({
+        contents: [
+          {
+            type: 'paragraph',
+            children: [{ type: 'image', url: '/hero.png', alt: 'hero' }],
+          },
+        ],
+      }),
+    );
+    expect(layers).toHaveLength(1);
+    expect((layers[0] as ImageLayer).content.src).toBe('/hero.png');
+  });
+
+  it('drops the layer entirely when the requested image index is out of range', () => {
+    const layers = resolveTokens(
+      [imageLayer('a', '{image:99}'), imageLayer('b', '/keep.png')],
+      block({
+        contents: [
+          {
+            type: 'paragraph',
+            children: [{ type: 'image', url: '/one.png', alt: '' }],
+          },
+        ],
+      }),
+    );
+    expect(layers).toHaveLength(1);
+    expect(layers[0].id).toBe('b');
+  });
+
+  it('substitutes tokens in the alt text when the src is also a token', () => {
+    const layers = resolveTokens(
+      [imageLayer('a', '{image:0}', 'Image for {title}')],
+      block({
+        title: 'My Doc',
+        contents: [
+          {
+            type: 'paragraph',
+            children: [{ type: 'image', url: '/x.png', alt: '' }],
+          },
+        ],
+      }),
+    );
+    const img = layers[0] as ImageLayer;
+    expect(img.content.src).toBe('/x.png');
+    expect(img.content.alt).toBe('Image for My Doc');
+  });
+
+  it('passes through ImageLayer with no token in src', () => {
+    const layers = resolveTokens([imageLayer('a', '/static.png')], block());
+    expect((layers[0] as ImageLayer).content.src).toBe('/static.png');
+  });
+});
+
+describe('resolveTokens — other layer types', () => {
+  it('passes ShapeLayer / PathLayer through unchanged', () => {
+    const shape = {
+      id: 's',
+      type: 'shape' as const,
+      position: { x: 0, y: 0, width: 50, height: 50 },
+      content: { shape: 'rect' as const, fill: '#fff' },
+    };
+    const path = {
+      id: 'p',
+      type: 'path' as const,
+      position: { x: 0, y: 0, width: 100, height: 100 },
+      content: { d: 'M 0 0 L 100 100', stroke: '#000' },
+    };
+    const layers = resolveTokens([shape, path], block());
+    expect(layers).toEqual([shape, path]);
+  });
+});
+
+describe('resolveTokens — purity', () => {
+  it('does not mutate the input layers array or the layers themselves', () => {
+    const original = textLayer('a', '{title}');
+    const before = JSON.stringify(original);
+    resolveTokens([original], block({ title: 'X' }));
+    expect(JSON.stringify(original)).toBe(before);
+  });
+});

package/src/doc/templates/twoColumn.ts

@@ -12,8 +12,14 @@
 
 import type { Layer } from '../../schemas/Doc.js';
 import type { TwoColumnInput, TemplateContext } from '../../schemas/BlockTemplates.js';
-import { scaledFontSize } from '../../schemas/BlockTemplates.js';
-import { resolveColorScheme, getThemeFont } from '../utils/themeUtils.js';
+import {
+  resolveColorScheme,
+  getThemeFont,
+  themedEntrance,
+  themedFontSize,
+  themedSurfaceGradient,
+} from '../utils/themeUtils.js';
+import { withAlpha } from '../../schemas/colorUtils.js';
 import { getTwoColumnPositions } from '../../schemas/LayoutStrategy.js';
 
 export function twoColumn(input: TwoColumnInput, context: TemplateContext): Layer[] {
@@ -33,10 +39,17 @@ export function twoColumn(input: TwoColumnInput, context: TemplateContext): Laye
   // Column width ~42% for side-by-side, ~85% for stacked
   const columnWidth = isStacked ? '85%' : '42%';
 
-  // Calculate font sizes based on viewport
-  const headerFontSize = scaledFontSize(32, context, false);
-  const labelFontSize = scaledFontSize(44, context, true);
-  const sublabelFontSize = scaledFontSize(22, context, false);
+  // Calculate font sizes based on viewport. The header is the block's
+  // title, so it sits a step ABOVE the column labels in the hierarchy —
+  // it used to render smaller and dimmer than the labels, which read as
+  // an inverted hierarchy.
+  const headerFontSize = themedFontSize(36, context, true);
+  const labelFontSize = themedFontSize(44, context, true);
+  const sublabelFontSize = themedFontSize(22, context, false);
+
+  // Panels drop below the header band so the title never overlaps them.
+  const panelTop = header && !isStacked ? 22 : 15;
+  const panelHeight = header && !isStacked ? 64 : 70;
 
   const layers: Layer[] = [
     // Background — subtle gradient to add depth
@@ -45,38 +58,41 @@ export function twoColumn(input: TwoColumnInput, context: TemplateContext): Laye
       id: 'bg',
       content: {
         shape: 'rect',
-        fill: `linear-gradient(135deg, ${theme.colors.background} 0%, #16202e 100%)`,
+        fill: themedSurfaceGradient(context, 135),
       },
       position: { x: 0, y: 0, width: '100%', height: '100%' },
     },
   ];
 
   if (!isStacked) {
-    // Left column background panel
+    // Column background panels — tinted from the theme text color so
+    // they stay visible on light and dark surfaces alike.
+    const panelFill = withAlpha(theme.colors.text, 0.05);
     layers.push({
       type: 'shape',
       id: 'left-panel',
       content: {
         shape: 'rect',
-        fill: 'rgba(255, 255, 255, 0.04)',
+        fill: panelFill,
+        borderRadius: 12,
       },
-      position: { x: '3%', y: '15%', width: '44%', height: '70%' },
+      position: { x: '3%', y: `${panelTop}%`, width: '44%', height: `${panelHeight}%` },
     });
 
-    // Right column background panel
     layers.push({
       type: 'shape',
       id: 'right-panel',
       content: {
         shape: 'rect',
-        fill: 'rgba(255, 255, 255, 0.04)',
+        fill: panelFill,
+        borderRadius: 12,
       },
-      position: { x: '53%', y: '15%', width: '44%', height: '70%' },
+      position: { x: '53%', y: `${panelTop}%`, width: '44%', height: `${panelHeight}%` },
     });
   }
 
-  // Header position adjusts based on layout
-  const headerY = isStacked ? '12%' : '22%';
+  // Header position adjusts based on layout — always clear of the panels.
+  const headerY = isStacked ? '8%' : '12%';
 
   // Add header if provided
   if (header) {
@@ -88,12 +104,13 @@ export function twoColumn(input: TwoColumnInput, context: TemplateContext): Laye
         style: {
           fontSize: headerFontSize,
           fontFamily: getThemeFont(context, 'title'),
-          color: theme.colors.textMuted,
+          fontWeight: 'bold',
+          color: theme.colors.text,
           textAlign: 'center',
         },
       },
       position: { x: '50%', y: headerY, anchor: 'center' },
-      animation: { type: 'fadeIn', duration: 0.8 },
+      animation: themedEntrance(context, 'text', { type: 'fadeIn', duration: 0.8 }),
     });
   }
 
@@ -110,13 +127,12 @@ export function twoColumn(input: TwoColumnInput, context: TemplateContext): Laye
     rightY = header ? '60%' : '55%';
     rightSublabelY = header ? '70%' : '65%';
   } else {
-    // Landscape/square: side by side — vertically centered in panels (15%-85%)
-    const baseY = header ? '47%' : '45%';
-    const sublabelOffset = header ? '58%' : '56%';
-    leftY = baseY;
-    leftSublabelY = sublabelOffset;
-    rightY = baseY;
-    rightSublabelY = sublabelOffset;
+    // Landscape/square: side by side — vertically centered in the panels.
+    const panelCenter = panelTop + panelHeight / 2;
+    leftY = `${panelCenter - 4}%`;
+    leftSublabelY = `${panelCenter + 7}%`;
+    rightY = `${panelCenter - 4}%`;
+    rightSublabelY = `${panelCenter + 7}%`;
   }
 
   // Left column (or top in portrait)
@@ -140,7 +156,7 @@ export function twoColumn(input: TwoColumnInput, context: TemplateContext): Laye
       anchor: 'center',
       width: columnWidth,
     },
-    animation: { type: 'fadeIn', duration: 1 },
+    animation: themedEntrance(context, 'text', { type: 'fadeIn', duration: 1 }),
   });
 
   if (left.sublabel) {
@@ -167,9 +183,11 @@ export function twoColumn(input: TwoColumnInput, context: TemplateContext): Laye
     });
   }
 
-  // Visual connector between columns (bold arrow)
-  const connectorFontSize = scaledFontSize(120, context, true);
-  const connectorY = isStacked ? '48%' : '50%'; // Centered in viewport
+  // Visual connector between columns — sized to fit inside the gutter
+  // between the panels (a 120px glyph used to cross both panel edges),
+  // tinted from the theme text color so it shows on any surface.
+  const connectorFontSize = themedFontSize(64, context, true);
+  const connectorY = isStacked ? '48%' : `${panelTop + panelHeight / 2}%`;
   const connectorSymbol = isStacked ? '\u2193' : '\u2192'; // ↓ for stacked, → for side-by-side
 
   layers.push({
@@ -181,7 +199,7 @@ export function twoColumn(input: TwoColumnInput, context: TemplateContext): Laye
         fontSize: connectorFontSize,
         fontFamily: getThemeFont(context, 'title'),
         fontWeight: 'bold',
-        color: 'rgba(255, 255, 255, 0.6)',
+        color: withAlpha(theme.colors.text, 0.45),
         textAlign: 'center',
       },
     },
@@ -214,7 +232,7 @@ export function twoColumn(input: TwoColumnInput, context: TemplateContext): Laye
       anchor: 'center',
       width: columnWidth,
     },
-    animation: { type: 'fadeIn', duration: 1, delay: 0.5 },
+    animation: themedEntrance(context, 'text', { type: 'fadeIn', duration: 1, delay: 0.5 }),
   });
 
   if (right.sublabel) {

package/src/doc/templates/videoPullQuote.ts

@@ -17,18 +17,21 @@
 
 import type { Layer } from '../../schemas/Doc.js';
 import type { VideoPullQuoteInput, TemplateContext } from '../../schemas/BlockTemplates.js';
-import { scaledFontSize } from '../../schemas/BlockTemplates.js';
-import { getThemeFont } from '../utils/themeUtils.js';
+import { getThemeFont, themedEntrance, themedFontSize } from '../utils/themeUtils.js';
+import { estimateTextHeight } from './captionUtils.js';
 
 export function videoPullQuote(input: VideoPullQuoteInput, context: TemplateContext): Layer[] {
   const { text, attribution, backgroundVideo } = input;
+  const { viewport } = context;
 
   // Guard: backgroundVideo is required
   if (!backgroundVideo?.src) return [];
 
-  const quoteFontSize = scaledFontSize(52, context, true);
-  const attrFontSize = scaledFontSize(24, context, false);
-  const decoFontSize = scaledFontSize(200, context, true);
+  const quoteFontSize = themedFontSize(52, context, true);
+  const attrFontSize = themedFontSize(26, context, false);
+  const decoFontSize = themedFontSize(200, context, true);
+  const quoteLineHeight = 1.4;
+  const quoteYPct = attribution ? 45 : 50;
 
   const layers: Layer[] = [
     // Full-bleed background video clip
@@ -90,22 +93,29 @@ export function videoPullQuote(input: VideoPullQuoteInput, context: TemplateCont
           fontFamily: getThemeFont(context, 'title'),
           color: '#ffffff',
           textAlign: 'center',
-          lineHeight: 1.5,
+          lineHeight: quoteLineHeight,
           shadow: true,
         },
       },
       position: {
         x: '50%',
-        y: attribution ? '45%' : '50%',
+        y: `${quoteYPct}%`,
         anchor: 'center',
-        width: '80%',
+        width: '72%',
       },
-      animation: { type: 'fadeIn', duration: 2 },
+      animation: themedEntrance(context, 'text', { type: 'fadeIn', duration: 2 }),
     },
   ];
 
-  // Attribution
+  // Attribution \u2014 hangs just below the quote's estimated bottom edge so
+  // the two read as one lockup instead of stranding near the bottom.
   if (attribution) {
+    const quoteWidthPx = 0.72 * viewport.width;
+    const quoteHeightPx = estimateTextHeight(text, quoteFontSize, quoteWidthPx, quoteLineHeight);
+    const attrYPct = Math.min(
+      82,
+      quoteYPct + ((quoteHeightPx / 2 + quoteFontSize * 1.7) / viewport.height) * 100,
+    );
     layers.push({
       type: 'text',
       id: 'attribution',
@@ -114,14 +124,14 @@ export function videoPullQuote(input: VideoPullQuoteInput, context: TemplateCont
         style: {
           fontSize: attrFontSize,
           fontFamily: getThemeFont(context, 'body'),
-          color: 'rgba(255, 255, 255, 0.7)',
+          color: 'rgba(255, 255, 255, 0.85)',
           textAlign: 'center',
           shadow: true,
         },
       },
       position: {
         x: '50%',
-        y: '72%',
+        y: `${attrYPct}%`,
         anchor: 'center',
       },
       animation: { type: 'fadeIn', duration: 1, delay: 1.5 },

package/src/doc/templates/videoWithCaption.ts

@@ -17,8 +17,8 @@
 
 import type { Layer } from '../../schemas/Doc.js';
 import type { VideoWithCaptionInput, TemplateContext } from '../../schemas/BlockTemplates.js';
-import { scaledFontSize } from '../../schemas/BlockTemplates.js';
-import { getThemeFont } from '../utils/themeUtils.js';
+import { getThemeFont, shouldUseShadow, themedFontSize } from '../utils/themeUtils.js';
+import { withAlpha } from '../../schemas/colorUtils.js';
 import { cleanCaption } from './captionUtils.js';
 
 export function videoWithCaption(input: VideoWithCaptionInput, context: TemplateContext): Layer[] {
@@ -37,8 +37,8 @@ export function videoWithCaption(input: VideoWithCaptionInput, context: Template
   const caption = rawCaption ? cleanCaption(rawCaption) : rawCaption;
   const { theme, layout } = context;
 
-  const captionFontSize = scaledFontSize(36, context, false);
-  const creditFontSize = scaledFontSize(16, context, false);
+  const captionFontSize = themedFontSize(36, context, false);
+  const creditFontSize = themedFontSize(16, context, false);
 
   const layers: Layer[] = [
     // Background video clip
@@ -60,14 +60,19 @@ export function videoWithCaption(input: VideoWithCaptionInput, context: Template
     },
   ];
 
-  // Caption text at bottom with gradient for readability
+  // Caption text at bottom with gradient for readability. The scrim is
+  // tinted from the theme background so the theme text color on top of it
+  // stays readable in light and dark themes alike; it fades toward the
+  // frame edge the caption sits on.
   if (caption) {
+    const bg = theme.colors.background;
+    const scrimAngle = captionPosition === 'top' ? 180 : 0;
     layers.push({
       type: 'shape',
       id: 'caption-gradient',
       content: {
         shape: 'rect',
-        fill: 'linear-gradient(0deg, rgba(0,0,0,0.7) 0%, rgba(0,0,0,0.3) 60%, transparent 100%)',
+        fill: `linear-gradient(${scrimAngle}deg, ${withAlpha(bg, 0.8)} 0%, ${withAlpha(bg, 0.35)} 60%, ${withAlpha(bg, 0)} 100%)`,
       },
       position: {
         x: 0,
@@ -90,7 +95,7 @@ export function videoWithCaption(input: VideoWithCaptionInput, context: Template
           fontFamily: getThemeFont(context, 'body'),
           color: theme.colors.text,
           textAlign: 'center',
-          shadow: true,
+          shadow: shouldUseShadow(context),
         },
       },
       position: {
@@ -113,7 +118,7 @@ export function videoWithCaption(input: VideoWithCaptionInput, context: Template
         style: {
           fontSize: creditFontSize,
           fontFamily: getThemeFont(context, 'body'),
-          color: 'rgba(255, 255, 255, 0.5)',
+          color: withAlpha(theme.colors.text, 0.65),
           textAlign: 'right',
         },
       },