@bendyline/squisq 1.5.0 → 1.5.1

package/src/doc/markdownToDoc.ts

@@ -45,6 +45,8 @@ import { estimateReadingTime } from '../timing/readingTime.js';
 import { resolveTemplateName, isContainerTemplate } from './templates/index.js';
 import { isDataFence, parseDataFence, findFirstTable, extractTableData } from './structuredData.js';
 import { extractMediaFromContents } from './mediaAnnotations.js';
+import { extractTemplateBlocksFromContents } from './annotationBlocks.js';
+import type { ParsedAnnotation } from './standaloneAnnotation.js';
 import { profileBlockContents, pickAutoTemplate } from '../recommend/templates.js';
 import { deriveTemplateInputs } from './templateInputs.js';
 import type { MediaClip } from '../schemas/Media.js';
@@ -145,6 +147,16 @@ function createIdGenerator() {
     used.set(id, Math.max(used.get(id) ?? 0, 1));
   };
 
+  // Slug + dedupe from arbitrary text (used for heading-less standalone
+  // annotation blocks, which have no MarkdownHeading to slug from). Shares
+  // the same `used` map so a standalone id can't collide with a heading id.
+  generate.fromText = (text: string): string => {
+    const base = slugify(text);
+    const count = used.get(base) ?? 0;
+    used.set(base, count + 1);
+    return count === 0 ? base : `${base}-${count + 1}`;
+  };
+
   return generate;
 }
 
@@ -196,6 +208,47 @@ function pinnedHeadingMeta(heading: MarkdownHeading | undefined): CoercedBlockMe
   return { ...fromAnnotation, ...fromPandoc };
 }
 
+/**
+ * Pinned block-meta for any block: the heading pins ({@link pinnedHeadingMeta})
+ * for heading blocks, or the standalone-annotation params for heading-less
+ * standalone blocks. Lets a standalone `{[quote duration=8]}` pin timing the
+ * same way a heading annotation would.
+ */
+function pinnedMeta(block: Block): CoercedBlockMeta {
+  if (block.sourceHeading) return pinnedHeadingMeta(block.sourceHeading);
+  if (block.sourceAnnotation?.params) {
+    return coerceAnnotationValues(block.sourceAnnotation.params).blockMeta;
+  }
+  return {};
+}
+
+/**
+ * Rebuild a block list, lifting standalone `{[…]}` template annotations out of
+ * each block's body into heading-less sibling blocks (recursing into children
+ * first). See {@link extractTemplateBlocksFromContents}.
+ */
+function expandStandaloneAnnotations(
+  blocks: Block[],
+  makeId: (parsed: ParsedAnnotation) => string,
+  defaultDuration: number,
+): Block[] {
+  const out: Block[] = [];
+  for (const block of blocks) {
+    if (block.children && block.children.length > 0) {
+      block.children = expandStandaloneAnnotations(block.children, makeId, defaultDuration);
+    }
+    const { leading, blocks: produced } = extractTemplateBlocksFromContents(block.contents, {
+      makeId,
+      defaultDuration,
+    });
+    if (produced.length > 0) {
+      block.contents = leading;
+    }
+    out.push(block, ...produced);
+  }
+  return out;
+}
+
 export function markdownToDoc(markdownDoc: MarkdownDocument, options?: MarkdownToDocOptions): Doc {
   const articleId = options?.articleId ?? 'markdown-doc';
   const defaultTemplate = options?.defaultTemplate ?? 'sectionHeader';
@@ -203,7 +256,7 @@ export function markdownToDoc(markdownDoc: MarkdownDocument, options?: MarkdownT
   const idGenerator = options?.generateId ? null : createIdGenerator();
   const generateId = options?.generateId ?? idGenerator!;
 
-  const rootBlocks: Block[] = [];
+  let rootBlocks: Block[] = [];
   const diagnostics: DocDiagnostic[] = [];
   let headingIndex = 0;
 
@@ -375,6 +428,30 @@ export function markdownToDoc(markdownDoc: MarkdownDocument, options?: MarkdownT
     rootBlocks.shift();
   }
 
+  // Standalone `{[templateName …]}` paragraphs (non-media) become heading-less
+  // template blocks; the body after each one, up to the next annotation,
+  // becomes its `contents`. Done after media extraction (so media names keep
+  // their meaning) and before structured-data parsing (so `json data` fences
+  // attach to the produced blocks). Produced blocks are inserted as siblings
+  // following the block whose body held the annotation.
+  const makeStandaloneId = (parsed: ParsedAnnotation): string => {
+    const base = parsed.params.title ?? parsed.template ?? 'block';
+    return idGenerator ? idGenerator.fromText(base) : slugify(base);
+  };
+  rootBlocks = expandStandaloneAnnotations(rootBlocks, makeStandaloneId, defaultDuration);
+  // A leading preamble whose entire body was consumed into standalone blocks
+  // is now empty — drop it so it doesn't leave a phantom slide.
+  if (
+    rootBlocks.length > 0 &&
+    !rootBlocks[0].sourceHeading &&
+    !rootBlocks[0].standaloneAnnotation &&
+    (rootBlocks[0].contents?.length ?? 0) === 0 &&
+    (rootBlocks[0].children?.length ?? 0) === 0 &&
+    !rootBlocks[0].media
+  ) {
+    rootBlocks.shift();
+  }
+
   const allBlocks = flattenBlocks(rootBlocks);
 
   // Structured template data: ```json data / ```yaml data fences in a
@@ -435,7 +512,7 @@ export function markdownToDoc(markdownDoc: MarkdownDocument, options?: MarkdownT
   // Skip blocks that pinned an explicit duration via a heading attribute —
   // author intent wins over reading-time heuristics.
   for (const block of allBlocks) {
-    if (pinnedHeadingMeta(block.sourceHeading).duration != null) continue;
+    if (pinnedMeta(block).duration != null) continue;
     const bodyText = getBlockBodyText(block);
     if (bodyText.length > 0) {
       const estimate = estimateReadingTime(bodyText);
@@ -451,7 +528,7 @@ export function markdownToDoc(markdownDoc: MarkdownDocument, options?: MarkdownT
   // sequence after them.
   let currentTime = 0;
   for (const block of allBlocks) {
-    const explicitStart = pinnedHeadingMeta(block.sourceHeading).startTime;
+    const explicitStart = pinnedMeta(block).startTime;
     if (explicitStart == null) {
       block.startTime = currentTime;
     }

package/src/doc/mediaAnnotations.ts

@@ -9,47 +9,21 @@
  * annotations, so quoting/escaping behave identically.
  */
 
-import {
-  matchTrailingTemplateAnnotation,
-  tokenizeAttrTokens,
-  splitKeyValueToken,
-} from '../markdown/attrTokens.js';
 import { parseTimeSeconds } from '../markdown/annotationCoercion.js';
 import type { MarkdownBlockNode } from '../markdown/types.js';
 import type { MediaClip } from '../schemas/Media.js';
+import { parseStandaloneAnnotation, type ParsedAnnotation } from './standaloneAnnotation.js';
 
 /** Annotation template names that produce a timed media clip. */
 const MEDIA_TEMPLATES = new Set(['audio', 'video', 'media']);
 
-interface ParsedAnnotation {
-  template?: string;
-  params: Record<string, string>;
-}
-
 /**
- * Parse a paragraph node that is *exactly* a `{[…]}` annotation (nothing
- * before or after). Returns the template + params, or null when the node
- * isn't a standalone annotation.
+ * Whether a standalone-annotation template name is a media name
+ * (`audio`/`video`/`media`). The standalone template-block extractor uses
+ * this to leave media annotations to {@link extractMediaFromContents}.
  */
-function parseStandaloneAnnotation(node: MarkdownBlockNode): ParsedAnnotation | null {
-  if (node.type !== 'paragraph') return null;
-  const children = node.children ?? [];
-  if (children.length !== 1 || children[0].type !== 'text') return null;
-  const text = children[0].value.trim();
-  const match = matchTrailingTemplateAnnotation(text);
-  // index 0 means the whole (trimmed) paragraph is the annotation.
-  if (!match || match.index !== 0) return null;
-
-  const tokens = tokenizeAttrTokens(match.inner.trim());
-  const firstIsParam = tokens.length > 0 && tokens[0].indexOf('=') > 0;
-  const template = firstIsParam || tokens.length === 0 ? undefined : tokens[0];
-  const startIdx = firstIsParam ? 0 : 1;
-  const params: Record<string, string> = {};
-  for (let i = startIdx; i < tokens.length; i++) {
-    const kv = splitKeyValueToken(tokens[i]);
-    if (kv) params[kv.key] = kv.value;
-  }
-  return { template, params };
+export function isMediaAnnotationName(name: string | undefined): boolean {
+  return name != null && MEDIA_TEMPLATES.has(name);
 }
 
 function time(raw: string | undefined): number | null {
@@ -67,7 +41,15 @@ function toMediaClip(parsed: ParsedAnnotation, id: string): MediaClip | null {
   const kind: MediaClip['kind'] = template === 'video' ? 'video' : 'audio';
   const anchor: MediaClip['anchor'] =
     params.anchor === 'document' || params.span === 'document' ? 'document' : 'block';
-  const clip: MediaClip = { id, src, kind, startAt: time(params.startAt) ?? 0, anchor };
+  // `startAt` is canonical; `startTime` is accepted as an alias (it is the
+  // heading-attribute spelling, so authors reach for it here too).
+  const clip: MediaClip = {
+    id,
+    src,
+    kind,
+    startAt: time(params.startAt ?? params.startTime) ?? 0,
+    anchor,
+  };
 
   const clipStart = time(params.clipStart);
   const clipEnd = time(params.clipEnd);

package/src/doc/standaloneAnnotation.ts

@@ -0,0 +1,58 @@
+/**
+ * Standalone-paragraph annotation parser.
+ *
+ * A paragraph whose entire trimmed text is exactly a `{[…]}` annotation
+ * (nothing before or after) is a *standalone annotation*. Two features share
+ * this shape:
+ *
+ * - **Media annotations** (`{[audio …]}` / `{[video …]}`) — lifted into typed
+ *   {@link import('../schemas/Media.js').MediaClip}s by `mediaAnnotations.ts`.
+ * - **Standalone template blocks** (`{[quote]}`, `{[statHighlight …]}`, …) —
+ *   turned into heading-less {@link import('../schemas/Doc.js').Block}s by
+ *   `annotationBlocks.ts`.
+ *
+ * Both call the single parser here so the annotation grammar (quoting,
+ * escaping, first-token-is-template) stays identical to the heading form.
+ */
+
+import {
+  matchTrailingTemplateAnnotation,
+  tokenizeAttrTokens,
+  splitKeyValueToken,
+} from '../markdown/attrTokens.js';
+import type { MarkdownBlockNode } from '../markdown/types.js';
+
+/** The template name + params parsed out of a standalone `{[…]}` paragraph. */
+export interface ParsedAnnotation {
+  /** First bare token, when the annotation leads with one (e.g. `quote`). */
+  template?: string;
+  /** Remaining `key=value` tokens, unquoted/unescaped. */
+  params: Record<string, string>;
+}
+
+/**
+ * Parse a paragraph node that is *exactly* a `{[…]}` annotation (nothing
+ * before or after). Returns the template + params, or null when the node
+ * isn't a standalone annotation (not a paragraph, more than one child, a
+ * non-text child such as a resolved inline icon, or trailing text).
+ */
+export function parseStandaloneAnnotation(node: MarkdownBlockNode): ParsedAnnotation | null {
+  if (node.type !== 'paragraph') return null;
+  const children = node.children ?? [];
+  if (children.length !== 1 || children[0].type !== 'text') return null;
+  const text = children[0].value.trim();
+  const match = matchTrailingTemplateAnnotation(text);
+  // index 0 means the whole (trimmed) paragraph is the annotation.
+  if (!match || match.index !== 0) return null;
+
+  const tokens = tokenizeAttrTokens(match.inner.trim());
+  const firstIsParam = tokens.length > 0 && tokens[0].indexOf('=') > 0;
+  const template = firstIsParam || tokens.length === 0 ? undefined : tokens[0];
+  const startIdx = firstIsParam ? 0 : 1;
+  const params: Record<string, string> = {};
+  for (let i = startIdx; i < tokens.length; i++) {
+    const kv = splitKeyValueToken(tokens[i]);
+    if (kv) params[kv.key] = kv.value;
+  }
+  return { template, params };
+}

package/src/doc/structuredData.ts

@@ -27,10 +27,12 @@
  *    didn't provide them explicitly.
  *
  * YAML support is a documented subset (this package has no YAML
- * dependency): top-level `key: scalar`, `key: [inline, array]`, and
- * `key:` followed by an indented `- item` block sequence whose items are
- * scalars or inline arrays. Nested maps are rejected with a clear error —
- * use a `json data` fence for deeply nested input.
+ * dependency): top-level `key: scalar`, `key: [inline, array]`, `key:`
+ * followed by an indented `- item` block sequence (scalars or inline
+ * arrays), and `key:` followed by *one level* of indented `subkey: scalar`
+ * lines (a nested map, e.g. `center:` + indented `lat:` / `lng:`). Deeper
+ * nesting, and mixing list items with mapping keys under one key, are
+ * rejected with a clear error — use a `json data` fence for those.
  */
 
 import type {
@@ -79,17 +81,42 @@ export function parseDataFence(node: MarkdownCodeBlock): DataFenceParseResult {
         return { error: 'JSON data fence must contain a top-level object ({"key": …})' };
       }
       return { data: parsed as Record<string, unknown> };
-    } catch (err) {
+    } catch (err: unknown) {
       return { error: `invalid JSON: ${err instanceof Error ? err.message : String(err)}` };
     }
   }
   try {
     return { data: parseYamlSubset(node.value) };
-  } catch (err) {
+  } catch (err: unknown) {
     return { error: `invalid YAML: ${err instanceof Error ? err.message : String(err)}` };
   }
 }
 
+/**
+ * Return a new contents array with the first data fence's code content
+ * replaced by `data` (pretty-printed JSON). The fence node keeps its
+ * language and `data` marker; only `value` changes. When no data fence
+ * exists, a new ` ```json data ` fence is appended instead.
+ *
+ * Pure: neither `contents` nor its nodes are mutated. This is the write
+ * half of the data-fence channel — editors update `block.templateData`
+ * and call this to reflect the change back into `block.contents`.
+ */
+export function replaceDataFence(
+  contents: MarkdownBlockNode[],
+  data: Record<string, unknown>,
+): MarkdownBlockNode[] {
+  const value = JSON.stringify(data, null, 2);
+  const index = contents.findIndex((node) => node.type === 'code' && isDataFence(node));
+  if (index < 0) {
+    const fence: MarkdownCodeBlock = { type: 'code', lang: 'json', meta: 'data', value };
+    return [...contents, fence];
+  }
+  const next = [...contents];
+  next[index] = { ...(contents[index] as MarkdownCodeBlock), value };
+  return next;
+}
+
 // ============================================
 // YAML subset parser
 // ============================================
@@ -153,30 +180,72 @@ function parseInlineValue(raw: string): unknown {
 export function parseYamlSubset(src: string): Record<string, unknown> {
   const result: Record<string, unknown> = {};
   const lines = src.split('\n');
-  let pendingListKey: string | null = null;
+
+  // Open block under the most recent `key:` line: whether its children are a
+  // block sequence (`- …`) or a nested map (`subkey: …`) is decided by the
+  // first indented child; `childIndent` pins the one allowed child depth.
+  let pendingKey: string | null = null;
+  let pendingKind: 'list' | 'map' | null = null;
+  let childIndent = -1;
 
   for (let i = 0; i < lines.length; i++) {
     const line = lines[i];
     const trimmed = line.trim();
     if (!trimmed || trimmed.startsWith('#')) continue;
 
-    const indented = /^\s/.test(line);
+    const indent = line.length - line.trimStart().length;
 
-    if (indented && trimmed.startsWith('- ')) {
-      if (!pendingListKey) {
-        throw new Error(`line ${i + 1}: list item without a preceding "key:" line`);
+    if (indent > 0) {
+      if (!pendingKey) {
+        throw new Error(`line ${i + 1}: unexpected indented line without a preceding "key:" line`);
+      }
+      if (childIndent < 0) childIndent = indent;
+      if (indent > childIndent) {
+        throw new Error(
+          `line ${i + 1}: nesting deeper than one level is not supported — use a \`\`\`json data fence for nested input`,
+        );
+      }
+
+      if (trimmed.startsWith('- ')) {
+        if (pendingKind === 'map') {
+          throw new Error(
+            `line ${i + 1}: cannot mix list items and mapping keys under "${pendingKey}"`,
+          );
+        }
+        pendingKind = 'list';
+        (result[pendingKey] as unknown[]).push(parseInlineValue(trimmed.slice(2)));
+        continue;
       }
-      (result[pendingListKey] as unknown[]).push(parseInlineValue(trimmed.slice(2)));
-      continue;
-    }
 
-    if (indented) {
-      throw new Error(
-        `line ${i + 1}: nested mappings are not supported — use a \`\`\`json data fence for nested input`,
-      );
+      // Otherwise this is a nested `subkey: value` mapping line.
+      if (pendingKind === 'list') {
+        throw new Error(
+          `line ${i + 1}: cannot mix mapping keys and list items under "${pendingKey}"`,
+        );
+      }
+      const subColon = trimmed.indexOf(':');
+      if (subColon < 1) {
+        throw new Error(`line ${i + 1}: expected "key: value"`);
+      }
+      const subValue = trimmed.slice(subColon + 1).trim();
+      if (subValue === '') {
+        // A nested `subkey:` opening its own block would be a second level.
+        throw new Error(
+          `line ${i + 1}: nesting deeper than one level is not supported — use a \`\`\`json data fence for nested input`,
+        );
+      }
+      if (pendingKind !== 'map') {
+        pendingKind = 'map';
+        result[pendingKey] = {};
+      }
+      (result[pendingKey] as Record<string, unknown>)[trimmed.slice(0, subColon).trim()] =
+        parseInlineValue(subValue);
+      continue;
     }
 
-    pendingListKey = null;
+    pendingKey = null;
+    pendingKind = null;
+    childIndent = -1;
     const colonIdx = trimmed.indexOf(':');
     if (colonIdx < 1) {
       throw new Error(`line ${i + 1}: expected "key: value"`);
@@ -185,9 +254,11 @@ export function parseYamlSubset(src: string): Record<string, unknown> {
     const rawValue = trimmed.slice(colonIdx + 1).trim();
 
     if (rawValue === '') {
-      // `key:` opens a block sequence; items follow as indented `- …` lines.
+      // `key:` opens a block: an indented `- …` sequence or a `subkey: …`
+      // map. Default to an empty list so a `key:` with no children stays
+      // back-compatible (`{ key: [] }`); the map branch replaces it wholesale.
       result[key] = [];
-      pendingListKey = key;
+      pendingKey = key;
     } else {
       result[key] = parseInlineValue(rawValue);
     }

package/src/doc/templates/__tests__/customTemplate.test.ts

@@ -70,7 +70,7 @@ describe('makeCustomTemplateFn', () => {
     expect((layers[0] as TextLayer).content.text).toBe('Hello, World!');
   });
 
-  it('returns layers unchanged when context.block is missing', () => {
+  it('falls back to the input block when context.block is missing', () => {
     const fn = makeCustomTemplateFn(
       defn([
         {
@@ -82,8 +82,27 @@ describe('makeCustomTemplateFn', () => {
       ]),
     );
     const ctx = createTemplateContext(DEFAULT_THEME, 0, 1, VIEWPORT_PRESETS.landscape);
+    // No ctx.block set; the fn resolves against `input` instead. The
+    // default input carries no title, so {title} collapses to empty.
     const layers = fn(makeInput(), ctx);
-    expect((layers[0] as TextLayer).content.text).toBe('{title}');
+    expect((layers[0] as TextLayer).content.text).toBe('');
+  });
+
+  it('resolves {attr:key} from the input block when context.block is missing', () => {
+    const fn = makeCustomTemplateFn(
+      defn([
+        {
+          id: 't',
+          type: 'text',
+          position: { x: '0%', y: '0%', width: '100%', height: '10%' },
+          content: { text: '{attr:role}', style: { fontSize: 24, color: '#000' } },
+        },
+      ]),
+    );
+    const ctx = createTemplateContext(DEFAULT_THEME, 0, 1, VIEWPORT_PRESETS.landscape);
+    const input = { ...makeInput(), templateOverrides: { role: 'lead' } } as RawLayersInput;
+    const layers = fn(input, ctx);
+    expect((layers[0] as TextLayer).content.text).toBe('lead');
   });
 
   it('preserves %-based positions verbatim — they resolve at SSR render time', () => {

package/src/doc/templates/comparisonBar.ts

@@ -18,15 +18,22 @@ import {
 } from '../utils/themeUtils.js';
 
 export function comparisonBar(input: ComparisonBarInput, context: TemplateContext): Layer[] {
-  const { leftLabel, leftValue, rightLabel, rightValue, unit, colorScheme = 'blue' } = input;
+  const { leftLabel, rightLabel, unit, colorScheme = 'blue' } = input;
   const { theme, viewport } = context;
   const colors = resolveColorScheme(context, colorScheme);
 
+  // Defensive: coerce non-finite values to 0. Callers should pass real numbers,
+  // but a NaN would otherwise render as literal "NaN" text and collapse every
+  // bar/label to a `NaN%` position, cramming the block against its left edge.
+  const leftValue = Number.isFinite(input.leftValue) ? input.leftValue : 0;
+  const rightValue = Number.isFinite(input.rightValue) ? input.rightValue : 0;
+
   const labelFontSize = themedFontSize(28, context, false);
   const valueFontSize = themedFontSize(48, context, true);
 
   // Format values for display
   const formatValue = (v: number): string => {
+    if (!Number.isFinite(v)) return '—';
     if (v >= 1_000_000) return `${(v / 1_000_000).toFixed(1)}M`;
     if (v >= 1_000) return `${(v / 1_000).toFixed(v >= 10_000 ? 0 : 1)}K`;
     return v.toLocaleString();

package/src/doc/templates/coverBlock.ts

@@ -42,6 +42,25 @@ export interface CoverBlockInput {
   imageTreatment?: 'none' | 'mono' | 'duotone' | 'warm' | 'cool';
 }
 
+/** Base (pre-viewport-scale) font size for a full-size cover title. */
+const COVER_TITLE_BASE_PX = 120;
+/** Title length (chars) that still reads well at the full base size. */
+const COVER_TITLE_COMFORTABLE_CHARS = 26;
+/** Readability floor so very long titles never shrink to nothing. */
+const COVER_TITLE_MIN_BASE_PX = 62;
+
+/**
+ * Compute the base cover-title font size for a given title, shrinking long
+ * titles so their wrapped block fits the frame. Returns the pre-viewport-scale
+ * value expected by {@link themedFontSize}; short titles get the full base.
+ */
+export function fitCoverTitleSize(title: string): number {
+  const len = title.trim().length;
+  if (len <= COVER_TITLE_COMFORTABLE_CHARS) return COVER_TITLE_BASE_PX;
+  const scaled = COVER_TITLE_BASE_PX * Math.sqrt(COVER_TITLE_COMFORTABLE_CHARS / len);
+  return Math.max(COVER_TITLE_MIN_BASE_PX, Math.round(scaled));
+}
+
 /**
  * Generate cover block layers from StartBlockConfig.
  */
@@ -50,8 +69,16 @@ export function coverBlock(input: CoverBlockInput, context: TemplateContext): La
   const { heroSrc, heroAlt, title, subtitle, ambientMotion, heroCredit, heroLicense } = input;
   const { theme, layout } = context;
 
-  // Scale font sizes for viewport - cover titles are larger than regular title blocks
-  const titleFontSize = themedFontSize(120, context, true);
+  // Scale font sizes for viewport - cover titles are larger than regular title blocks.
+  // The cover title wraps within maxTextWidth but does not otherwise shrink, so a long
+  // title (e.g. "Seattle: The Emerald City That Rebuilt Itself on Top of Itself") wrapped
+  // to three 120px lines overflows the frame and is clipped by the player controls.
+  // Auto-fit the base size to title length so long titles stay within the frame. The
+  // wrapped title's total height grows with fontSize² × length (line count ∝ length ×
+  // fontSize / width, line height ∝ fontSize), so scaling the base by √(threshold/length)
+  // keeps the wrapped block's area roughly constant past the threshold. Short titles are
+  // unaffected (scale clamps at 1).
+  const titleFontSize = themedFontSize(fitCoverTitleSize(title), context, true);
   const subtitleFontSize = themedFontSize(40, context, false);
 
   const layers: Layer[] = [];

package/src/doc/templates/customTemplate.ts

@@ -12,7 +12,7 @@
  * UI and the resolver, not here.
  */
 
-import type { Layer } from '../../schemas/Doc.js';
+import type { Block, Layer } from '../../schemas/Doc.js';
 import type {
   RawLayersInput,
   TemplateContext,
@@ -38,8 +38,14 @@ import { resolveTokens } from './tokens/resolveTokens.js';
 export function makeCustomTemplateFn(
   def: CustomTemplateDefinition,
 ): TemplateFunction<RawLayersInput> {
-  return (_input: RawLayersInput, context: TemplateContext): Layer[] => {
-    if (!context.block) return def.layers.slice();
-    return resolveTokens(def.layers, context.block);
+  return (input: RawLayersInput, context: TemplateContext): Layer[] => {
+    // `{attr:…}` reads the source block's `templateOverrides` /
+    // `templateData` / `metadata`. Prefer `context.block` (the raw
+    // block the expander attaches); fall back to `input` (the merged
+    // TemplateBlock, itself a Block superset) so attributes still
+    // resolve if `context.block` is ever absent.
+    const block = context.block ?? (input as unknown as Block | undefined);
+    if (!block) return def.layers.slice() as Layer[];
+    return resolveTokens(def.layers, block);
   };
 }

package/src/doc/templates/factCard.ts

@@ -32,9 +32,11 @@ export function factCard(input: FactCardInput, context: TemplateContext): Layer[
   // Get layout adjustments if accent image is present
   const accentLayout = accentImage ? getAccentLayout(accentImage.position) : DEFAULT_LAYOUT;
 
-  // Scale font sizes for viewport
+  // Scale font sizes for viewport. The explanation sits at ~60% of the fact
+  // size — large enough to read comfortably as the secondary line while still
+  // clearly subordinate to the headline fact.
   const factFontSize = themedFontSize(56, context, true);
-  const explainFontSize = themedFontSize(28, context, false);
+  const explainFontSize = themedFontSize(34, context, false);
   const sourceFontSize = themedFontSize(20, context, false);
 
   const layers: Layer[] = [createBackgroundLayer('bg', themedSurfaceGradient(context, 170))];

package/src/doc/templates/imageWithCaption.ts

@@ -38,7 +38,7 @@ export function imageWithCaption(input: ImageWithCaptionInput, context: Template
   const treatment = themedImageTreatment(context, input.imageTreatment);
 
   // Scale font sizes for viewport
-  const captionFontSize = themedFontSize(36, context, false);
+  const captionFontSize = themedFontSize(30, context, false);
   const titleFontSize = themedFontSize(96, context, true);
   const subtitleFontSize = themedFontSize(36, context, false);
 
@@ -140,23 +140,23 @@ export function imageWithCaption(input: ImageWithCaptionInput, context: Template
 
   // STANDARD MODE: Caption at bottom
   if (caption) {
-    // Subtle gradient at bottom for caption readability (raised above media controls)
+    // Compact caption band raised above media controls. Long archival captions
+    // are clamped so they don't sprawl across the image.
     layers.push({
       type: 'shape',
       id: 'caption-gradient',
       content: {
         shape: 'rect',
-        fill: `linear-gradient(0deg, ${withAlpha(bg, 0.8)} 0%, ${withAlpha(bg, 0.35)} 60%, ${withAlpha(bg, 0)} 100%)`,
+        fill: `linear-gradient(90deg, ${withAlpha(bg, 0)}, ${withAlpha(bg, 0.78)} 16%, ${withAlpha(bg, 0.78)} 84%, ${withAlpha(bg, 0)})`,
       },
       position: {
         x: 0,
-        y: '65%',
+        y: '68%',
         width: '100%',
-        height: '35%',
+        height: '16%',
       },
     });
 
-    // Caption text - raised above media controls
     layers.push({
       type: 'text',
       id: 'caption',
@@ -168,13 +168,15 @@ export function imageWithCaption(input: ImageWithCaptionInput, context: Template
           color: theme.colors.text,
           textAlign: 'center',
           shadow: shouldUseShadow(context),
+          lineHeight: 1.18,
+          maxLines: 2,
         },
       },
       position: {
         x: '50%',
-        y: '82%',
+        y: '74%',
         anchor: 'center',
-        width: layout.maxTextWidth,
+        width: '78%',
       },
       animation: { type: 'fadeIn', duration: 1.5, delay: 0.5 },
     });

package/src/doc/templates/index.ts

@@ -27,6 +27,10 @@ import { expandPersistentLayers, wrapWithPersistentLayers } from './persistentLa
 import { applyRenderStyleToLayers } from '../utils/applyRenderStyle.js';
 import { resolveBlockTransition } from '../../schemas/Transitions.js';
 import { makeCustomTemplateFn } from './customTemplate.js';
+// Coerces inline `{[…]}` string params into typed template input. inputDescriptors
+// imports `resolveTemplateName` from this module in return; the cycle is benign
+// because every cross-reference lives inside a function body, not module init.
+import { coerceTemplateParams } from './inputDescriptors.js';
 import type { ViewportConfig } from '../../schemas/Viewport.js';
 import { VIEWPORT_PRESETS } from '../../schemas/Viewport.js';
 
@@ -197,11 +201,17 @@ export function expandTemplateBlock(
 
   // Effective template input: the block's own fields, then structured
   // body data (```json data fences / derived auto-template inputs), then
-  // `{[…]}` string overrides — the same merge order getLayers uses.
+  // `{[…]}` string overrides — the same merge order getLayers uses. Inline
+  // overrides are coerced to their typed shape (e.g. `center="47.6,-122.3"` →
+  // `{lat,lng}`); `templateOverrides` itself stays raw for round-tripping.
   const { templateData, templateOverrides } = templateBlock as Block;
   const input =
     templateData || templateOverrides
-      ? ({ ...templateBlock, ...templateData, ...templateOverrides } as TemplateBlock)
+      ? ({
+          ...templateBlock,
+          ...templateData,
+          ...coerceTemplateParams(templateBlock.template, templateOverrides ?? {}).input,
+        } as TemplateBlock)
       : templateBlock;
 
   // Generate layers from template with error handling