@bendyline/squisq 1.4.0 → 1.5.0

package/src/doc/templates/fallbackBlock.ts

@@ -0,0 +1,123 @@
+/**
+ * Fallback Block Rendering
+ *
+ * The graceful-degradation guarantee: a block whose template can't render —
+ * unknown template name, template function threw, or returned a non-array —
+ * still renders its heading and body text as a plain, readable card instead
+ * of a blank slide. A small notice line names the problem so authors (and
+ * agents reviewing screenshots) can see *why* the block degraded.
+ *
+ * This is intentionally not a registered template: it can't be requested by
+ * name, only reached when a requested template fails. See `getLayers()`.
+ */
+
+import type { Layer } from '../../schemas/Doc.js';
+import type { Block } from '../../schemas/Doc.js';
+import type { DocBlock, TemplateContext } from '../../schemas/BlockTemplates.js';
+import { resolveColorScheme, getThemeFont, themedFontSize } from '../utils/themeUtils.js';
+import { extractPlainText } from '../../markdown/utils.js';
+
+/** Cap body text so a long section doesn't overflow the card. */
+const MAX_BODY_CHARS = 600;
+
+/**
+ * Render a block's heading + body text as plain layers, with a notice line
+ * describing why the requested template didn't render.
+ *
+ * @param block   The block that failed to render via its template.
+ * @param context Template context (theme, viewport).
+ * @param notice  Short problem description, e.g. `Unknown template "photGrid"`.
+ */
+export function fallbackBlockLayers(
+  block: DocBlock,
+  context: TemplateContext,
+  notice: string,
+): Layer[] {
+  const colors = resolveColorScheme(context, 'blue');
+  const { layout } = context;
+
+  const title = (block as Block).title ?? (block as Block).id ?? '';
+  const body = extractBodyText(block as Block);
+
+  const layers: Layer[] = [
+    {
+      type: 'shape',
+      id: 'fallback-bg',
+      content: { shape: 'rect', fill: colors.bg },
+      position: { x: 0, y: 0, width: '100%', height: '100%' },
+    },
+  ];
+
+  if (title) {
+    layers.push({
+      type: 'text',
+      id: 'fallback-title',
+      content: {
+        text: title,
+        style: {
+          fontSize: themedFontSize(56, context, true),
+          fontFamily: getThemeFont(context, 'title'),
+          fontWeight: 'bold',
+          color: colors.text,
+          textAlign: 'center',
+        },
+      },
+      position: {
+        x: '50%',
+        y: body ? '28%' : '50%',
+        anchor: 'center',
+        width: layout.maxTextWidth,
+      },
+    });
+  }
+
+  if (body) {
+    layers.push({
+      type: 'text',
+      id: 'fallback-body',
+      content: {
+        text: body,
+        style: {
+          fontSize: themedFontSize(28, context),
+          fontFamily: getThemeFont(context, 'body'),
+          color: colors.text,
+          textAlign: 'center',
+        },
+      },
+      position: {
+        x: '50%',
+        y: '55%',
+        anchor: 'center',
+        width: layout.maxTextWidth,
+      },
+    });
+  }
+
+  layers.push({
+    type: 'text',
+    id: 'fallback-notice',
+    content: {
+      text: `⚠ ${notice}`,
+      style: {
+        fontSize: themedFontSize(18, context),
+        fontFamily: getThemeFont(context, 'body'),
+        color: `${colors.text}99`,
+        textAlign: 'center',
+      },
+    },
+    position: { x: '50%', y: '92%', anchor: 'center', width: layout.maxTextWidth },
+  });
+
+  return layers;
+}
+
+/** Plain text of a block's body contents, truncated for card display. */
+function extractBodyText(block: Block): string {
+  if (!block.contents || block.contents.length === 0) return '';
+  const text = block.contents
+    .map((node) => extractPlainText(node))
+    .join('\n')
+    .trim();
+  if (text.length <= MAX_BODY_CHARS) return text;
+  return `${text.slice(0, MAX_BODY_CHARS).trimEnd()}…`;
+}

package/src/doc/templates/featureBlock.ts

@@ -18,8 +18,12 @@ import type {
   RightFeatureInput,
   TemplateContext,
 } from '../../schemas/BlockTemplates.js';
-import { scaledFontSize } from '../../schemas/BlockTemplates.js';
-import { getThemeFont } from '../utils/themeUtils.js';
+import {
+  getThemeFont,
+  themedEntrance,
+  themedFontSize,
+  themedImageTreatment,
+} from '../utils/themeUtils.js';
 
 type FeatureInput = LeftFeatureInput | RightFeatureInput;
 
@@ -34,6 +38,8 @@ function buildFeatureLayers(
 ): Layer[] {
   const { imageSrc, imageAlt, imageWidth, imageHeight, title, body } = input;
   const { theme, layout } = context;
+
+  const treatment = themedImageTreatment(context, input.imageTreatment);
   // Treat the image as "sized" when the host gave us an explicit width
   // or height — that's our cue that the user resized the image in the
   // editor and we should respect that as a sizing hint instead of
@@ -44,8 +50,8 @@ function buildFeatureLayers(
   // behave consistently on narrow viewports.
   const stack = layout.stackColumns;
 
-  const titleFontSize = scaledFontSize(48, context, true);
-  const bodyFontSize = scaledFontSize(24, context, false);
+  const titleFontSize = themedFontSize(48, context, true);
+  const bodyFontSize = themedFontSize(24, context, false);
 
   // Image takes the full left or right half. The text column gets the
   // opposite half, with a comfortable inset so the text doesn't kiss
@@ -90,17 +96,17 @@ function buildFeatureLayers(
   }
 
   // Text-column geometry. `textX` is the LEFT edge of the column when
-  // the side is "left" (image left, text right), and the RIGHT edge of
-  // the column when the side is "right" — we use top-left / top-right
-  // anchors below so text reads left-aligned in both cases without
-  // having to flip the column origin manually.
+  // the side is "left" (image left, text right); when the side is
+  // "right" the column occupies the left half, inset from the card edge.
+  // The mirror lives in the layout only — fully right-aligned
+  // (ragged-left) running text on rightFeature was genuinely hard to read.
   const COLUMN_INSET = 4; // % of block width — padding from card edge / divider
   const textColumnWidth = stack ? 90 : 42;
   const textX = stack
     ? `${(100 - textColumnWidth) / 2}%`
     : side === 'left'
       ? `${50 + COLUMN_INSET}%` // text column starts just past the divider
-      : `${50 - COLUMN_INSET}%`; // right edge of left-half text column
+      : `${COLUMN_INSET + 2}%`; // left edge of the left-half text column
 
   // Stack the title above the body, with the pair vertically centered
   // in the text column. The title sits 8% above center; body sits 2%
@@ -108,8 +114,8 @@ function buildFeatureLayers(
   // sizes used by the inline preview gutter without overflowing.
   const titleY = stack ? '60%' : body ? '42%' : '50%';
   const bodyY = stack ? '78%' : title ? '55%' : '50%';
-  const textAnchor = side === 'right' && !stack ? 'top-right' : 'top-left';
-  const textAlign: 'left' | 'right' = side === 'right' && !stack ? 'right' : 'left';
+  const textAnchor = 'top-left';
+  const textAlign = 'left' as const;
 
   // Paint our own background so the text column has a theme-paired
   // surface to sit on. The host wrapper's surface isn't always theme-
@@ -136,6 +142,7 @@ function buildFeatureLayers(
         src: imageSrc,
         alt: imageAlt ?? title ?? '',
         fit: imageFit,
+        ...(treatment ? { treatment } : {}),
       },
       position: { x: imgX, y: imgY, width: imgW, height: imgH },
     });
@@ -162,7 +169,7 @@ function buildFeatureLayers(
         anchor: textAnchor,
         width: `${textColumnWidth}%`,
       },
-      animation: { type: 'fadeIn', duration: 0.8 },
+      animation: themedEntrance(context, 'text', { type: 'fadeIn', duration: 0.8 }),
     });
   }
 
@@ -186,7 +193,7 @@ function buildFeatureLayers(
         anchor: textAnchor,
         width: `${textColumnWidth}%`,
       },
-      animation: { type: 'fadeIn', duration: 0.8, delay: 0.2 },
+      animation: themedEntrance(context, 'text', { type: 'fadeIn', duration: 0.8, delay: 0.2 }),
     });
   }
 

package/src/doc/templates/fullBleedQuote.ts

@@ -10,8 +10,14 @@
 
 import type { Layer } from '../../schemas/Doc.js';
 import type { FullBleedQuoteInput, TemplateContext } from '../../schemas/BlockTemplates.js';
-import { scaledFontSize } from '../../schemas/BlockTemplates.js';
-import { resolveColorScheme, getThemeFont } from '../utils/themeUtils.js';
+import {
+  resolveColorScheme,
+  getTemplateHint,
+  getThemeFont,
+  shouldUseShadow,
+  themedFontSize,
+} from '../utils/themeUtils.js';
+import { oklchDarken } from '../../schemas/colorUtils.js';
 
 /**
  * Hint schema published for the theme validator + future customizer hint UI.
@@ -28,20 +34,21 @@ export const fullBleedQuoteHintSchema = {
 
 export function fullBleedQuote(input: FullBleedQuoteInput, context: TemplateContext): Layer[] {
   const { text, colorScheme = 'blue' } = input;
-  const { theme } = context;
   const colors = resolveColorScheme(context, colorScheme);
 
   // Massive font for dramatic impact
-  const textFontSize = scaledFontSize(120, context, true);
+  const textFontSize = themedFontSize(120, context, true);
 
   return [
-    // Background — dark radial vignette for cinematic feel
+    // Background — radial vignette built from the color scheme's own
+    // surface, so the card takes on the scheme (and the theme behind it)
+    // instead of vignetting every theme into hard black.
     {
       type: 'shape',
       id: 'bg',
       content: {
         shape: 'rect',
-        fill: `radial-gradient(ellipse at 50% 50%, ${theme.colors.backgroundLight} 0%, #000000 100%)`,
+        fill: `radial-gradient(ellipse at 50% 50%, ${colors.bg} 0%, ${oklchDarken(colors.bg, 0.12)} 100%)`,
       },
       position: { x: 0, y: 0, width: '100%', height: '100%' },
     },
@@ -58,7 +65,7 @@ export function fullBleedQuote(input: FullBleedQuoteInput, context: TemplateCont
           color: colors.text,
           textAlign: 'center',
           lineHeight: 1.2,
-          shadow: true,
+          shadow: shouldUseShadow(context),
         },
       },
       position: {
@@ -67,7 +74,10 @@ export function fullBleedQuote(input: FullBleedQuoteInput, context: TemplateCont
         anchor: 'center',
         width: '85%',
       },
-      animation: { type: 'fadeIn', duration: 1.5 },
+      animation:
+        getTemplateHint<string>(context, 'fullBleedQuote', 'entrance', 'subtle') === 'dramatic'
+          ? { type: 'zoomIn', duration: 0.8 }
+          : { type: 'fadeIn', duration: 1.5 },
     },
   ];
 }

package/src/doc/templates/imageWithCaption.ts

@@ -10,8 +10,13 @@
 
 import type { Layer } from '../../schemas/Doc.js';
 import type { ImageWithCaptionInput, 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';
 import { mapAmbientMotion } from './accentImage.js';
 
@@ -30,10 +35,12 @@ export function imageWithCaption(input: ImageWithCaptionInput, context: Template
   const caption = rawCaption ? cleanCaption(rawCaption) : rawCaption;
   const { theme, layout } = context;
 
+  const treatment = themedImageTreatment(context, input.imageTreatment);
+
   // Scale font sizes for viewport
-  const captionFontSize = scaledFontSize(36, context, false);
-  const titleFontSize = scaledFontSize(96, context, true);
-  const subtitleFontSize = scaledFontSize(36, context, false);
+  const captionFontSize = themedFontSize(36, context, false);
+  const titleFontSize = themedFontSize(96, context, true);
+  const subtitleFontSize = themedFontSize(36, context, false);
 
   // Determine animation based on ambientMotion setting
   // Support both new 'ambientMotion' and legacy 'kenBurns' property
@@ -54,12 +61,18 @@ export function imageWithCaption(input: ImageWithCaptionInput, context: Template
         fit: 'cover',
         credit: imageCredit,
         license: imageLicense,
+        ...(treatment ? { treatment } : {}),
       },
       position: { x: 0, y: 0, width: '100%', height: '100%' },
       animation: imageAnimation,
     },
   ];
 
+  // Scrim gradients are tinted from the theme background so the theme
+  // text color painted on top stays readable by construction — a fixed
+  // black scrim put dark theme text on a dark band in light themes.
+  const bg = theme.colors.background;
+
   // TITLE MODE: Large centered title over hero image (like cover slide)
   if (isTitle && caption) {
     // Full gradient overlay for title readability (similar to cover slide)
@@ -68,7 +81,7 @@ export function imageWithCaption(input: ImageWithCaptionInput, context: Template
       id: 'title-gradient',
       content: {
         shape: 'rect',
-        fill: 'linear-gradient(0deg, rgba(0,0,0,0.8) 0%, rgba(0,0,0,0.4) 40%, rgba(0,0,0,0.1) 70%, transparent 100%)',
+        fill: `linear-gradient(0deg, ${withAlpha(bg, 0.85)} 0%, ${withAlpha(bg, 0.45)} 40%, ${withAlpha(bg, 0.1)} 70%, ${withAlpha(bg, 0)} 100%)`,
       },
       position: { x: 0, y: 0, width: '100%', height: '100%' },
     });
@@ -85,7 +98,7 @@ export function imageWithCaption(input: ImageWithCaptionInput, context: Template
           fontWeight: 'bold',
           color: theme.colors.text,
           textAlign: 'center',
-          shadow: true,
+          shadow: shouldUseShadow(context),
         },
       },
       position: {
@@ -133,7 +146,7 @@ export function imageWithCaption(input: ImageWithCaptionInput, context: Template
       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(0deg, ${withAlpha(bg, 0.8)} 0%, ${withAlpha(bg, 0.35)} 60%, ${withAlpha(bg, 0)} 100%)`,
       },
       position: {
         x: 0,
@@ -154,7 +167,7 @@ export function imageWithCaption(input: ImageWithCaptionInput, context: Template
           fontFamily: getThemeFont(context, 'body'),
           color: theme.colors.text,
           textAlign: 'center',
-          shadow: true,
+          shadow: shouldUseShadow(context),
         },
       },
       position: {