@bendyline/squisq 1.4.0 → 1.5.0

package/src/doc/templates/listBlock.ts

@@ -10,8 +10,13 @@
 
 import type { Layer } from '../../schemas/Doc.js';
 import type { ListBlockInput, TemplateContext } from '../../schemas/BlockTemplates.js';
-import { scaledFontSize } from '../../schemas/BlockTemplates.js';
-import { getThemeFont } from '../utils/themeUtils.js';
+import {
+  getThemeFont,
+  shouldUseShadow,
+  themedEntrance,
+  themedFontSize,
+  themedImageTreatment,
+} from '../utils/themeUtils.js';
 import { createAccentLayers, getAccentLayout, adjustY, DEFAULT_LAYOUT } from './accentImage.js';
 
 export function listBlock(input: ListBlockInput, context: TemplateContext): Layer[] {
@@ -27,8 +32,8 @@ export function listBlock(input: ListBlockInput, context: TemplateContext): Laye
   // Get layout adjustments if accent image is present
   const accentLayout = accentImage ? getAccentLayout(accentImage.position) : DEFAULT_LAYOUT;
 
-  const titleFontSize = scaledFontSize(44, context, true);
-  const itemFontSize = scaledFontSize(34, context, false);
+  const titleFontSize = themedFontSize(44, context, true);
+  const itemFontSize = themedFontSize(34, context, false);
 
   const layers: Layer[] = [
     // Background — gradient
@@ -45,11 +50,27 @@ export function listBlock(input: ListBlockInput, context: TemplateContext): Laye
 
   // Add accent image layers
   if (accentImage) {
-    layers.push(...createAccentLayers(accentImage, input.id));
+    layers.push(
+      ...createAccentLayers(
+        accentImage,
+        input.id,
+        themedImageTreatment(context, input.imageTreatment),
+      ),
+    );
   }
 
+  // Left edge of the text column — derived from the center+width pair so
+  // the title and items share one left axis instead of a centered title
+  // floating over a left-aligned column. Falls back to a safe 8% if the
+  // layout strings ever turn out unparseable (they're authored, but
+  // defensive against future edits to the accent-layout types).
+  const centerX = parseFloat(accentLayout.textCenterX);
+  const widthPct = parseFloat(accentLayout.textWidth);
+  const leftX =
+    Number.isFinite(centerX) && Number.isFinite(widthPct) ? `${centerX - widthPct / 2}%` : '8%';
+
   // Title if provided
-  const startY = title ? 30 : 22;
+  const startY = title ? 34 : 26;
   if (title) {
     layers.push({
       type: 'text',
@@ -61,35 +82,36 @@ export function listBlock(input: ListBlockInput, context: TemplateContext): Laye
           fontFamily: getThemeFont(context, 'title'),
           fontWeight: 'bold',
           color: theme.colors.text,
-          textAlign: 'center',
-          shadow: !!accentImage,
+          textAlign: 'left',
+          shadow: shouldUseShadow(context),
         },
       },
       position: {
-        x: accentLayout.textCenterX,
-        y: adjustY('16%', accentLayout),
-        anchor: 'center',
+        x: leftX,
+        y: adjustY('20%', accentLayout),
+        width: accentLayout.textWidth,
       },
-      animation: { type: 'fadeIn', duration: 1 },
+      animation: themedEntrance(context, 'text', { type: 'fadeIn', duration: 1 }),
     });
   }
 
-  // Left edge of the text column — derived from the center+width pair so
-  // items sit flush with the column's left margin instead of being
-  // centered. Falls back to a safe 8% if the layout strings ever turn
-  // out unparseable (they're authored, but defensive against future
-  // edits to the accent-layout types).
-  const centerX = parseFloat(accentLayout.textCenterX);
-  const widthPct = parseFloat(accentLayout.textWidth);
-  const leftX =
-    Number.isFinite(centerX) && Number.isFinite(widthPct) ? `${centerX - widthPct / 2}%` : '8%';
-
-  // Calculate vertical spacing for items. We keep the available band
-  // (startY → endY) but use a tighter line-height (1.2) so wrapped
-  // items don't bleed into the next entry as aggressively as the old
-  // 1.4 value did.
-  const endY = 80;
-  const spacing = items.length > 1 ? (endY - startY) / (items.length - 1) : 0;
+  // Stack items with a fixed compact gap rather than stretching them
+  // across the available band. Distributing items across (startY → 80%)
+  // left big vertical gaps for short lists and made the slide read as a
+  // sparse menu instead of a tight enumeration; conversely a bare
+  // line-height gap read as a cramped paragraph — 18px of air keeps each
+  // entry its own line without breaking the group.
+  //
+  // Spacing = item line-height (34px base × 1.2) + 18px gap, expressed
+  // as % of the 1080px design canvas (~5.4%). Wrapped items push the
+  // next entry down via their own line-height, so this sets the
+  // minimum baseline-to-baseline distance for unwrapped items.
+  const LIST_ITEM_BASE_PX = 34;
+  const LIST_ITEM_LINE_HEIGHT = 1.2;
+  const LIST_ITEM_GAP_PX = 18;
+  const DESIGN_HEIGHT_PX = 1080;
+  const spacing =
+    ((LIST_ITEM_BASE_PX * LIST_ITEM_LINE_HEIGHT + LIST_ITEM_GAP_PX) / DESIGN_HEIGHT_PX) * 100;
 
   // List items with staggered animation
   for (let i = 0; i < items.length; i++) {
@@ -107,7 +129,7 @@ export function listBlock(input: ListBlockInput, context: TemplateContext): Laye
           color: theme.colors.text,
           textAlign: 'left',
           lineHeight: 1.2,
-          shadow: !!accentImage,
+          shadow: shouldUseShadow(context),
         },
       },
       position: {
@@ -115,7 +137,11 @@ export function listBlock(input: ListBlockInput, context: TemplateContext): Laye
         y: adjustY(`${y}%`, accentLayout),
         width: accentLayout.textWidth,
       },
-      animation: { type: 'fadeIn', duration: 0.8, delay: 0.3 + 0.3 * i },
+      animation: themedEntrance(context, 'text', {
+        type: 'fadeIn',
+        duration: 0.8,
+        delay: 0.3 + 0.3 * i,
+      }),
     });
   }
 

package/src/doc/templates/mapBlock.ts

@@ -14,8 +14,8 @@
 
 import type { Layer } from '../../schemas/Doc.js';
 import type { MapBlockInput, 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 { mapAmbientMotion } from './accentImage.js';
 
 export function mapBlock(input: MapBlockInput, context: TemplateContext): Layer[] {
@@ -32,8 +32,8 @@ export function mapBlock(input: MapBlockInput, context: TemplateContext): Layer[
   const { theme, layout } = context;
 
   // Scale font sizes for viewport
-  const titleFontSize = scaledFontSize(64, context, true);
-  const captionFontSize = scaledFontSize(32, context, false);
+  const titleFontSize = themedFontSize(64, context, true);
+  const captionFontSize = themedFontSize(32, context, false);
 
   // Determine animation based on ambientMotion setting
   const mapAnimation = mapAmbientMotion(ambientMotion);
@@ -56,17 +56,21 @@ export function mapBlock(input: MapBlockInput, context: TemplateContext): Layer[
     },
   ];
 
+  // Overlay bands are tinted from the theme background so the theme text
+  // color on them stays readable in light and dark themes alike; they
+  // fade out toward the map so the band doesn't read as a hard seam.
+  const bg = theme.colors.background;
+
   // Add title overlay if provided
   if (title) {
-    // Gradient overlay at top for title readability
     layers.push({
       type: 'shape',
       id: 'title-overlay',
       content: {
         shape: 'rect',
-        fill: 'rgba(0,0,0,0.6)',
+        fill: `linear-gradient(180deg, ${withAlpha(bg, 0.85)} 0%, ${withAlpha(bg, 0.6)} 70%, ${withAlpha(bg, 0)} 100%)`,
       },
-      position: { x: 0, y: 0, width: '100%', height: '18%' },
+      position: { x: 0, y: 0, width: '100%', height: '20%' },
     });
 
     // Title text - positioned at top of slide
@@ -81,7 +85,7 @@ export function mapBlock(input: MapBlockInput, context: TemplateContext): Layer[
           fontWeight: 'bold',
           color: theme.colors.text,
           textAlign: 'center',
-          shadow: true,
+          shadow: shouldUseShadow(context),
         },
       },
       position: {
@@ -96,15 +100,14 @@ export function mapBlock(input: MapBlockInput, context: TemplateContext): Layer[
 
   // Add caption if provided
   if (caption) {
-    // Gradient overlay at bottom for caption readability
     layers.push({
       type: 'shape',
       id: 'caption-overlay',
       content: {
         shape: 'rect',
-        fill: 'rgba(0,0,0,0.6)',
+        fill: `linear-gradient(0deg, ${withAlpha(bg, 0.85)} 0%, ${withAlpha(bg, 0.6)} 70%, ${withAlpha(bg, 0)} 100%)`,
       },
-      position: { x: 0, y: '82%', width: '100%', height: '18%' },
+      position: { x: 0, y: '80%', width: '100%', height: '20%' },
     });
 
     // Caption text
@@ -118,7 +121,7 @@ export function mapBlock(input: MapBlockInput, context: TemplateContext): Layer[
           fontFamily: getThemeFont(context, 'body'),
           color: theme.colors.text,
           textAlign: 'center',
-          shadow: true,
+          shadow: shouldUseShadow(context),
         },
       },
       position: {

package/src/doc/templates/metadata.ts

@@ -0,0 +1,120 @@
+/**
+ * Canonical, framework-free UI metadata for every built-in block template.
+ *
+ * This is the single source of truth for the human-readable label and the
+ * one-sentence description of each template id in {@link templateRegistry}.
+ * The editor's `TemplatePicker` renders its gallery from this map (joining
+ * each id with a locally-defined SVG icon, which can't live in this
+ * framework-free package), so a template only has to be added here and to
+ * `templateRegistry` for it to surface in the editor.
+ *
+ * `templateMetadata.test.ts` asserts this map and `templateRegistry` stay
+ * exactly 1:1 — adding a template to one without the other fails the build.
+ *
+ * Order matters: pickers iterate this object's insertion order, so it doubles
+ * as the canonical gallery order.
+ */
+
+export interface TemplateMetadata {
+  /** Human-readable label shown in pickers (e.g. "Image with Caption"). */
+  label: string;
+  /** One-sentence description of when to reach for this template. */
+  description: string;
+}
+
+export const TEMPLATE_METADATA: Record<string, TemplateMetadata> = {
+  title: {
+    label: 'Title',
+    description: 'A bold opening slide with large title text, perfect for covers and chapters.',
+  },
+  sectionHeader: {
+    label: 'Section Header',
+    description: 'A clean section break with a prominent title and optional subtitle.',
+  },
+  statHighlight: {
+    label: 'Stat Highlight',
+    description: 'Showcases a single key number or metric with supporting context.',
+  },
+  quote: {
+    label: 'Quote',
+    description: 'Displays a stylized pull quote with decorative marks and attribution.',
+  },
+  factCard: {
+    label: 'Fact Card',
+    description: 'Presents a focused fact or insight with a labeled header and body text.',
+  },
+  twoColumn: {
+    label: 'Two Column',
+    description: 'Divides the slide into two equal side-by-side content columns.',
+  },
+  dateEvent: {
+    label: 'Date Event',
+    description: 'Highlights a date-based event or milestone with a prominent date display.',
+  },
+  imageWithCaption: {
+    label: 'Image with Caption',
+    description: 'Displays a full-bleed image with an optional caption below.',
+  },
+  leftFeature: {
+    label: 'Left Feature',
+    description: 'Image on the left, title and body text stacked on the right.',
+  },
+  rightFeature: {
+    label: 'Right Feature',
+    description: 'Image on the right, title and body text stacked on the left.',
+  },
+  map: {
+    label: 'Map',
+    description: 'Embeds an interactive map centered on a geographic location.',
+  },
+  fullBleedQuote: {
+    label: 'Full Bleed Quote',
+    description: 'A full-width quote that spans the entire slide for maximum impact.',
+  },
+  list: {
+    label: 'List',
+    description: 'Renders a bulleted or numbered list in a clean, card-style layout.',
+  },
+  photoGrid: {
+    label: 'Photo Grid',
+    description: 'Arranges multiple photos in a 2×2 or 3×3 mosaic grid.',
+  },
+  definitionCard: {
+    label: 'Definition Card',
+    description: 'Shows a term and its definition in a structured, dictionary-style card.',
+  },
+  comparisonBar: {
+    label: 'Comparison Bar',
+    description: 'Visualizes two or more values side-by-side with labeled horizontal bars.',
+  },
+  pullQuote: {
+    label: 'Pull Quote',
+    description: 'A stylized pull quote with large decorative marks and centered text.',
+  },
+  videoWithCaption: {
+    label: 'Video with Caption',
+    description: 'Embeds a video player with an optional caption below.',
+  },
+  videoPullQuote: {
+    label: 'Video Pull Quote',
+    description: 'Combines a video panel with a highlighted pull quote side-by-side.',
+  },
+  dataTable: {
+    label: 'Data Table',
+    description: 'Renders tabular data in a clean, styled table with a header row.',
+  },
+  diagram: {
+    label: 'Diagram',
+    description:
+      'Renders sub-headings as connected nodes — edit visually as a node-and-edge diagram.',
+  },
+  layout: {
+    label: 'Layout',
+    description:
+      "Free-form 2D canvas — drag layers into place. Use for one-off block layouts that don't fit a template.",
+  },
+  drawing: {
+    label: 'Drawing',
+    description: 'Free-form sketches — draw shapes, paths, and text directly on a 2D surface.',
+  },
+};

package/src/doc/templates/persistentLayers.ts

@@ -20,12 +20,15 @@ import type {
   GradientBackgroundConfig,
   ImageBackgroundConfig,
   PatternBackgroundConfig,
+  VignetteConfig,
+  AmbientGradientConfig,
   TitleCaptionConfig,
   CornerBrandingConfig,
   ProgressIndicatorConfig,
 } from '../../schemas/BlockTemplates.js';
 import type { Theme } from '../../schemas/Theme.js';
 import { isPersistentLayerTemplate } from '../../schemas/BlockTemplates.js';
+import { oklchDarken, withAlpha } from '../../schemas/colorUtils.js';
 
 // ============================================
 // Gradient Presets
@@ -35,9 +38,11 @@ const GRADIENT_PRESETS: Record<string, string> = {
   'dark-vignette':
     'radial-gradient(ellipse at center, rgba(26,32,44,0.8) 0%, rgba(0,0,0,0.95) 100%)',
   'radial-dark': 'radial-gradient(ellipse at center, #1a202c 0%, #000000 100%)',
-  'warm-sunset': 'linear-gradient(135deg, rgba(124,58,48,0.9) 0%, rgba(26,32,44,0.95) 100%)',
+  // Warm presets deepen within their own hue — ending in the shared navy
+  // made warm themes drift cold halfway down the frame.
+  'warm-sunset': 'linear-gradient(135deg, rgba(124,58,48,0.9) 0%, rgba(46,20,16,0.95) 100%)',
   'cool-blue': 'linear-gradient(135deg, rgba(26,54,93,0.9) 0%, rgba(26,32,44,0.95) 100%)',
-  'earth-tones': 'linear-gradient(135deg, rgba(68,51,34,0.9) 0%, rgba(26,32,44,0.95) 100%)',
+  'earth-tones': 'linear-gradient(135deg, rgba(68,51,34,0.9) 0%, rgba(30,22,15,0.95) 100%)',
 };
 
 // ============================================
@@ -84,7 +89,9 @@ function expandImageBackground(config: ImageBackgroundConfig): Layer[] {
   const layers: Layer[] = [];
   const opacity = config.opacity ?? 0.4;
 
-  // Base image layer
+  // Base image layer. `blur` softens the photo into an atmosphere layer
+  // (the ImageLayer renderer over-scans blurred images so soft edges never
+  // reveal the frame).
   const imageLayer: Layer = {
     type: 'image',
     id: 'persistent-bg-image',
@@ -92,6 +99,7 @@ function expandImageBackground(config: ImageBackgroundConfig): Layer[] {
       src: config.src,
       alt: 'Background',
       fit: 'cover',
+      ...(config.blur != null && config.blur > 0 ? { blur: config.blur } : {}),
     },
     position: { x: 0, y: 0, width: '100%', height: '100%' },
     animation: config.ambientMotion
@@ -122,22 +130,79 @@ function expandImageBackground(config: ImageBackgroundConfig): Layer[] {
  * Expand a pattern background config to a Layer.
  */
 function expandPatternBackground(config: PatternBackgroundConfig): Layer {
-  const opacity = config.opacity ?? 0.1;
-  const color = config.color ?? `rgba(255,255,255,${opacity})`;
+  // 'noise' is film grain: a full-bleed rect whose paint is replaced by a
+  // static feTurbulence field clipped to the rect (see ShapeFilter).
+  if (config.pattern === 'noise') {
+    return {
+      type: 'shape',
+      id: 'persistent-grain',
+      content: {
+        shape: 'rect',
+        fill: '#000000',
+        filter: { type: 'noise', opacity: config.opacity ?? 0.05 },
+      },
+      position: { x: 0, y: 0, width: '100%', height: '100%' },
+    };
+  }
 
-  // Pattern as SVG data URI for rect patterns
-  // For simplicity, use a solid subtle color with reduced opacity
+  // dots / grid / diagonal render as native SVG <pattern> fills.
+  const opacity = config.opacity ?? 0.06;
   return {
     type: 'shape',
     id: 'persistent-bg-pattern',
     content: {
       shape: 'rect',
-      fill: color,
+      pattern: {
+        kind: config.pattern,
+        color: config.color ?? '#ffffff',
+        size: Math.round(24 * (config.scale ?? 1)),
+        opacity,
+      },
     },
     position: { x: 0, y: 0, width: '100%', height: '100%' },
   };
 }
 
+/**
+ * Expand a vignette config: transparent center darkening toward the frame
+ * edges. Rides the CSS-gradient rect path in the renderer.
+ */
+function expandVignette(config: VignetteConfig): Layer {
+  const strength = Math.max(0, Math.min(1, config.strength ?? 0.3));
+  const color = config.color ?? '#000000';
+  const edge = withAlpha(color, strength);
+  const clear = withAlpha(color, 0);
+  return {
+    type: 'shape',
+    id: 'persistent-vignette',
+    content: {
+      shape: 'rect',
+      fill: `radial-gradient(ellipse at center, ${clear} 55%, ${edge} 100%)`,
+    },
+    position: { x: 0, y: 0, width: '100%', height: '100%' },
+  };
+}
+
+/**
+ * Expand an ambient drifting gradient: an oversized surface gradient with
+ * a very slow Ken Burns loop. Deterministic (no randomness).
+ */
+function expandAmbientGradient(config: AmbientGradientConfig, theme?: Theme): Layer {
+  const from = config.from ?? theme?.colors.backgroundLight ?? '#1a202c';
+  const to = config.to ?? (theme ? oklchDarken(theme.colors.background, 0.04) : '#0f141d');
+  return {
+    type: 'shape',
+    id: 'persistent-ambient-gradient',
+    content: {
+      shape: 'rect',
+      fill: `linear-gradient(150deg, ${from} 0%, ${to} 100%)`,
+    },
+    // Oversized so the slow pan never reveals the frame edge.
+    position: { x: '-5%', y: '-5%', width: '110%', height: '110%' },
+    animation: { type: 'slowZoom', panDirection: 'left', duration: config.duration ?? 40 },
+  };
+}
+
 // ============================================
 // Overlay Layer Expansion
 // ============================================
@@ -349,7 +414,7 @@ function expandProgressIndicator(config: ProgressIndicatorConfig): Layer {
 /**
  * Expand a single persistent layer (template or raw) to raw Layer(s).
  */
-export function expandPersistentLayer(layer: PersistentLayer): Layer[] {
+export function expandPersistentLayer(layer: PersistentLayer, theme?: Theme): Layer[] {
   // If already a raw Layer, return as-is
   if (!isPersistentLayerTemplate(layer)) {
     return [layer as Layer];
@@ -367,6 +432,10 @@ export function expandPersistentLayer(layer: PersistentLayer): Layer[] {
       return expandImageBackground(config);
     case 'patternBackground':
       return [expandPatternBackground(config)];
+    case 'vignette':
+      return [expandVignette(config)];
+    case 'ambientGradient':
+      return [expandAmbientGradient(config, theme)];
     case 'titleCaption':
       return expandTitleCaption(config);
     case 'cornerBranding':
@@ -382,13 +451,19 @@ export function expandPersistentLayer(layer: PersistentLayer): Layer[] {
 /**
  * Expand all persistent layers in a config to raw Layer arrays.
  */
-export function expandPersistentLayers(layers: PersistentLayer[] | undefined): Layer[] {
+export function expandPersistentLayers(
+  layers: PersistentLayer[] | undefined,
+  theme?: Theme,
+): Layer[] {
   if (!layers || layers.length === 0) {
     return [];
   }
 
   // Use reduce+concat instead of flatMap for Coherent GT compatibility (ES2017)
-  return layers.reduce<Layer[]>((acc, layer) => acc.concat(expandPersistentLayer(layer)), []);
+  return layers.reduce<Layer[]>(
+    (acc, layer) => acc.concat(expandPersistentLayer(layer, theme)),
+    [],
+  );
 }
 
 // ============================================
@@ -520,3 +595,46 @@ export function getDocStyleConfig(
 export function getPersistentLayersFromTheme(theme: Theme): PersistentLayerConfig {
   return theme.persistentLayers ?? {};
 }
+
+/**
+ * Resolve the effective persistent-layer config for a doc: the doc's own
+ * config wins **wholesale** when present; only docs with no persistent
+ * layers inherit the theme's.
+ *
+ * Doc-wins-wholesale (rather than merging) protects pre-baked documents
+ * that carry their own background/branding layers — merging a theme's
+ * atmosphere on top of those would double up backgrounds and stack
+ * overlays the doc author never saw.
+ */
+export function resolvePersistentLayers(
+  doc: { persistentLayers?: PersistentLayerConfig },
+  theme: Theme,
+): PersistentLayerConfig | undefined {
+  const docConfig = doc.persistentLayers;
+  const hasDocLayers =
+    !!docConfig &&
+    ((docConfig.bottomLayers?.length ?? 0) > 0 || (docConfig.topLayers?.length ?? 0) > 0);
+  if (hasDocLayers) return docConfig;
+  const themeConfig = theme.persistentLayers;
+  const hasThemeLayers =
+    !!themeConfig &&
+    ((themeConfig.bottomLayers?.length ?? 0) > 0 || (themeConfig.topLayers?.length ?? 0) > 0);
+  return hasThemeLayers ? themeConfig : docConfig;
+}
+
+/**
+ * Compose a block's layers between pre-expanded persistent bottom/top
+ * layers, honoring the per-block `useBottomLayer` / `useTopLayer` opt-outs.
+ * Single shared implementation for `expandDocBlocks` and `getLayers`.
+ */
+export function wrapWithPersistentLayers(
+  layers: Layer[],
+  block: { useBottomLayer?: boolean; useTopLayer?: boolean },
+  bottomLayers: Layer[],
+  topLayers: Layer[],
+): Layer[] {
+  if (bottomLayers.length === 0 && topLayers.length === 0) return layers;
+  const useBottom = block.useBottomLayer !== false;
+  const useTop = block.useTopLayer !== false;
+  return [...(useBottom ? bottomLayers : []), ...layers, ...(useTop ? topLayers : [])];
+}

package/src/doc/templates/photoGrid.ts

@@ -17,12 +17,17 @@
 
 import type { Layer } from '../../schemas/Doc.js';
 import type { PhotoGridInput, TemplateContext } from '../../schemas/BlockTemplates.js';
-import { scaledFontSize } from '../../schemas/BlockTemplates.js';
-import { getThemeFont } from '../utils/themeUtils.js';
+import {
+  getThemeFont,
+  shouldUseShadow,
+  themedFontSize,
+  themedImageTreatment,
+} from '../utils/themeUtils.js';
+import { withAlpha } from '../../schemas/colorUtils.js';
 import { cleanCaption } from './captionUtils.js';
 
 /** Gap between images as percentage */
-const GAP = 0.5;
+const GAP = 1.2;
 
 export function photoGrid(input: PhotoGridInput, context: TemplateContext): Layer[] {
   const { images, caption: rawCaption, ambientMotion } = input;
@@ -33,24 +38,27 @@ export function photoGrid(input: PhotoGridInput, context: TemplateContext): Laye
   const caption = rawCaption ? cleanCaption(rawCaption) : rawCaption;
   const { theme, layout } = context;
 
+  const treatment = themedImageTreatment(context, input.imageTreatment);
+
   const layers: Layer[] = [
-    // Black background (visible in gaps between images)
+    // Theme surface background (visible in gaps between images)
     {
       type: 'shape',
       id: 'bg',
-      content: { shape: 'rect', fill: '#000000' },
+      content: { shape: 'rect', fill: theme.colors.background },
       position: { x: 0, y: 0, width: '100%', height: '100%' },
     },
   ];
 
-  // Reserve bottom space for caption — more room in landscape for larger text
-  const captionHeight = caption ? (layout.stackColumns ? 18 : 22) : 0;
+  // Reserve bottom space for caption — sized to the caption's one-to-two
+  // lines rather than a fixed fifth of the block (which left a dead band).
+  const captionHeight = caption ? (layout.stackColumns ? 16 : 14) : 0;
   const gridHeight = 100 - captionHeight;
 
   // Generate image positions based on count; stack vertically in portrait
   const positions = getGridPositions(images.length, gridHeight, layout.stackColumns);
 
-  const altFontSize = scaledFontSize(24, context, false);
+  const altFontSize = themedFontSize(24, context, false);
 
   for (let i = 0; i < Math.min(images.length, 4); i++) {
     const img = images[i];
@@ -92,6 +100,7 @@ export function photoGrid(input: PhotoGridInput, context: TemplateContext): Laye
         fit: 'cover',
         credit: img.credit,
         license: img.license,
+        ...(treatment ? { treatment } : {}),
       },
       position: {
         x: `${pos.x}%`,
@@ -109,14 +118,16 @@ export function photoGrid(input: PhotoGridInput, context: TemplateContext): Laye
 
   // Caption with gradient overlay
   if (caption) {
-    const captionFontSize = scaledFontSize(layout.stackColumns ? 28 : 40, context, false);
+    const captionFontSize = themedFontSize(layout.stackColumns ? 28 : 32, context, false);
 
+    // Caption band fades from the theme surface so the theme text color
+    // on it always reads (a fixed black band hid dark text in light themes).
     layers.push({
       type: 'shape',
       id: 'caption-bg',
       content: {
         shape: 'rect',
-        fill: 'linear-gradient(transparent, rgba(0,0,0,0.8))',
+        fill: `linear-gradient(${withAlpha(theme.colors.background, 0)}, ${withAlpha(theme.colors.background, 0.85)})`,
       },
       position: { x: 0, y: `${gridHeight - 4}%`, width: '100%', height: `${captionHeight + 4}%` },
     });
@@ -131,12 +142,12 @@ export function photoGrid(input: PhotoGridInput, context: TemplateContext): Laye
           fontFamily: getThemeFont(context, 'body'),
           color: theme.colors.text,
           textAlign: 'center',
-          shadow: true,
+          shadow: shouldUseShadow(context),
         },
       },
       position: {
         x: '50%',
-        y: `${gridHeight + (layout.stackColumns ? captionHeight / 2 : captionHeight * 0.3)}%`,
+        y: `${gridHeight + captionHeight / 2}%`,
         anchor: 'center',
         width: '90%',
       },