@bendyline/squisq 1.1.0 → 1.1.1

package/src/doc/templates/factCard.ts

@@ -13,6 +13,7 @@
 import type { Layer } from '../../schemas/Doc.js';
 import type { FactCardInput, TemplateContext } from '../../schemas/BlockTemplates.js';
 import { scaledFontSize } from '../../schemas/BlockTemplates.js';
+import { getThemeFont } from '../utils/themeUtils.js';
 import { createAccentLayers, getAccentLayout, adjustY, DEFAULT_LAYOUT } from './accentImage.js';
 import { createBackgroundLayer } from './captionUtils.js';
 
@@ -48,6 +49,7 @@ export function factCard(input: FactCardInput, context: TemplateContext): Layer[
       text: fact,
       style: {
         fontSize: factFontSize,
+        fontFamily: getThemeFont(context, 'title'),
         fontWeight: 'bold',
         color: theme.colors.text,
         textAlign: 'center',
@@ -72,6 +74,7 @@ export function factCard(input: FactCardInput, context: TemplateContext): Layer[
       text: explanation,
       style: {
         fontSize: explainFontSize,
+        fontFamily: getThemeFont(context, 'body'),
         color: theme.colors.textMuted,
         textAlign: 'center',
         lineHeight: 1.5,
@@ -96,6 +99,7 @@ export function factCard(input: FactCardInput, context: TemplateContext): Layer[
         text: source,
         style: {
           fontSize: sourceFontSize,
+          fontFamily: getThemeFont(context, 'body'),
           color: theme.colors.textMuted,
           textAlign: 'center',
           shadow: !!accentImage,

package/src/doc/templates/fullBleedQuote.ts

@@ -11,7 +11,7 @@
 import type { Layer } from '../../schemas/Doc.js';
 import type { FullBleedQuoteInput, TemplateContext } from '../../schemas/BlockTemplates.js';
 import { scaledFontSize } from '../../schemas/BlockTemplates.js';
-import { resolveColorScheme } from '../utils/themeUtils.js';
+import { resolveColorScheme, getThemeFont } from '../utils/themeUtils.js';
 
 export function fullBleedQuote(input: FullBleedQuoteInput, context: TemplateContext): Layer[] {
   const { text, colorScheme = 'blue' } = input;
@@ -40,6 +40,7 @@ export function fullBleedQuote(input: FullBleedQuoteInput, context: TemplateCont
         text,
         style: {
           fontSize: textFontSize,
+          fontFamily: getThemeFont(context, 'title'),
           fontWeight: 'bold',
           color: colors.text,
           textAlign: 'center',

package/src/doc/templates/imageWithCaption.ts

@@ -11,6 +11,7 @@
 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 { cleanCaption } from './captionUtils.js';
 import { mapAmbientMotion } from './accentImage.js';
 
@@ -80,6 +81,7 @@ export function imageWithCaption(input: ImageWithCaptionInput, context: Template
         text: caption,
         style: {
           fontSize: titleFontSize,
+          fontFamily: getThemeFont(context, 'title'),
           fontWeight: 'bold',
           color: theme.colors.text,
           textAlign: 'center',
@@ -104,6 +106,7 @@ export function imageWithCaption(input: ImageWithCaptionInput, context: Template
           text: subtitle,
           style: {
             fontSize: subtitleFontSize,
+            fontFamily: getThemeFont(context, 'body'),
             color: theme.colors.textMuted,
             textAlign: 'center',
             lineHeight: 1.5,
@@ -148,6 +151,7 @@ export function imageWithCaption(input: ImageWithCaptionInput, context: Template
         text: caption,
         style: {
           fontSize: captionFontSize,
+          fontFamily: getThemeFont(context, 'body'),
           color: theme.colors.text,
           textAlign: 'center',
           shadow: true,

package/src/doc/templates/listBlock.ts

@@ -11,6 +11,7 @@
 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 { createAccentLayers, getAccentLayout, adjustY, DEFAULT_LAYOUT } from './accentImage.js';
 
 export function listBlock(input: ListBlockInput, context: TemplateContext): Layer[] {
@@ -51,6 +52,7 @@ export function listBlock(input: ListBlockInput, context: TemplateContext): Laye
         text: title,
         style: {
           fontSize: titleFontSize,
+          fontFamily: getThemeFont(context, 'title'),
           fontWeight: 'bold',
           color: theme.colors.text,
           textAlign: 'center',
@@ -82,6 +84,7 @@ export function listBlock(input: ListBlockInput, context: TemplateContext): Laye
         text: itemText,
         style: {
           fontSize: itemFontSize,
+          fontFamily: getThemeFont(context, 'body'),
           color: theme.colors.text,
           lineHeight: 1.4,
           shadow: !!accentImage,

package/src/doc/templates/mapBlock.ts

@@ -15,6 +15,7 @@
 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 { mapAmbientMotion } from './accentImage.js';
 
 export function mapBlock(input: MapBlockInput, context: TemplateContext): Layer[] {
@@ -76,6 +77,7 @@ export function mapBlock(input: MapBlockInput, context: TemplateContext): Layer[
         text: title,
         style: {
           fontSize: titleFontSize,
+          fontFamily: getThemeFont(context, 'title'),
           fontWeight: 'bold',
           color: theme.colors.text,
           textAlign: 'center',
@@ -113,6 +115,7 @@ export function mapBlock(input: MapBlockInput, context: TemplateContext): Layer[
         text: caption,
         style: {
           fontSize: captionFontSize,
+          fontFamily: getThemeFont(context, 'body'),
           color: theme.colors.text,
           textAlign: 'center',
           shadow: true,

package/src/doc/templates/photoGrid.ts

@@ -18,6 +18,7 @@
 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 { cleanCaption } from './captionUtils.js';
 
 /** Gap between images as percentage */
@@ -72,6 +73,7 @@ export function photoGrid(input: PhotoGridInput, context: TemplateContext): Laye
           text: img.alt,
           style: {
             fontSize: altFontSize,
+            fontFamily: getThemeFont(context, 'body'),
             color: theme.colors.textMuted,
             textAlign: 'center' as const,
           },
@@ -126,6 +128,7 @@ export function photoGrid(input: PhotoGridInput, context: TemplateContext): Laye
         text: caption,
         style: {
           fontSize: captionFontSize,
+          fontFamily: getThemeFont(context, 'body'),
           color: theme.colors.text,
           textAlign: 'center',
           shadow: true,

package/src/doc/templates/pullQuote.ts

@@ -11,6 +11,7 @@
 import type { Layer } from '../../schemas/Doc.js';
 import type { PullQuoteInput, TemplateContext } from '../../schemas/BlockTemplates.js';
 import { scaledFontSize } from '../../schemas/BlockTemplates.js';
+import { getThemeFont } from '../utils/themeUtils.js';
 
 export function pullQuote(input: PullQuoteInput, context: TemplateContext): Layer[] {
   const { text, attribution, backgroundImage, ambientMotion } = input;
@@ -57,6 +58,7 @@ export function pullQuote(input: PullQuoteInput, context: TemplateContext): Laye
         text: '\u201C',
         style: {
           fontSize: decoFontSize,
+          fontFamily: getThemeFont(context, 'title'),
           color: 'rgba(255, 255, 255, 0.08)',
           textAlign: 'center',
         },
@@ -76,6 +78,7 @@ export function pullQuote(input: PullQuoteInput, context: TemplateContext): Laye
         text,
         style: {
           fontSize: quoteFontSize,
+          fontFamily: getThemeFont(context, 'title'),
           color: '#ffffff',
           textAlign: 'center',
           lineHeight: 1.5,
@@ -101,6 +104,7 @@ export function pullQuote(input: PullQuoteInput, context: TemplateContext): Laye
         text: `\u2014 ${attribution}`,
         style: {
           fontSize: attrFontSize,
+          fontFamily: getThemeFont(context, 'body'),
           color: 'rgba(255, 255, 255, 0.7)',
           textAlign: 'center',
           shadow: true,

package/src/doc/templates/quoteBlock.ts

@@ -13,6 +13,7 @@
 import type { Layer } from '../../schemas/Doc.js';
 import type { QuoteBlockInput, TemplateContext } from '../../schemas/BlockTemplates.js';
 import { scaledFontSize } from '../../schemas/BlockTemplates.js';
+import { getThemeFont } from '../utils/themeUtils.js';
 import { createAccentLayers, getAccentLayout, adjustY, DEFAULT_LAYOUT } from './accentImage.js';
 import { createBackgroundLayer } from './captionUtils.js';
 
@@ -50,6 +51,7 @@ export function quoteBlock(input: QuoteBlockInput, context: TemplateContext): La
       text: '\u201C',
       style: {
         fontSize: decorativeQuoteFontSize,
+        fontFamily: getThemeFont(context, 'title'),
         color: 'rgba(255, 255, 255, 0.06)',
         textAlign: 'center',
       },
@@ -70,6 +72,7 @@ export function quoteBlock(input: QuoteBlockInput, context: TemplateContext): La
       text: quote,
       style: {
         fontSize: quoteFontSize,
+        fontFamily: getThemeFont(context, 'title'),
         color: theme.colors.text,
         textAlign: 'center',
         lineHeight: 1.6,
@@ -94,6 +97,7 @@ export function quoteBlock(input: QuoteBlockInput, context: TemplateContext): La
         text: `— ${attribution}`,
         style: {
           fontSize: attrFontSize,
+          fontFamily: getThemeFont(context, 'body'),
           color: theme.colors.textMuted,
           textAlign: 'center',
           shadow: !!accentImage,

package/src/doc/templates/sectionHeader.ts

@@ -12,10 +12,10 @@
 import type { Layer, AnimationType } from '../../schemas/Doc.js';
 import type { SectionHeaderInput, TemplateContext } from '../../schemas/BlockTemplates.js';
 import { scaledFontSize } from '../../schemas/BlockTemplates.js';
-import { resolveColorScheme } from '../utils/themeUtils.js';
+import { resolveColorScheme, getThemeFont } from '../utils/themeUtils.js';
 
 export function sectionHeader(input: SectionHeaderInput, context: TemplateContext): Layer[] {
-  const { title, colorScheme = 'blue', imageSrc, imageAlt, ambientMotion } = input;
+  const { title = '', colorScheme = 'blue', imageSrc, imageAlt, ambientMotion } = input;
   const { layout } = context;
   const colors = resolveColorScheme(context, colorScheme);
 
@@ -86,6 +86,7 @@ export function sectionHeader(input: SectionHeaderInput, context: TemplateContex
       text: title,
       style: {
         fontSize: titleFontSize,
+        fontFamily: getThemeFont(context, 'title'),
         fontWeight: 'bold',
         color: imageSrc ? '#ffffff' : colors.text,
         textAlign: 'center',

package/src/doc/templates/statHighlight.ts

@@ -13,7 +13,7 @@
 import type { Layer } from '../../schemas/Doc.js';
 import type { StatHighlightInput, TemplateContext } from '../../schemas/BlockTemplates.js';
 import { scaledFontSize } from '../../schemas/BlockTemplates.js';
-import { resolveColorScheme } from '../utils/themeUtils.js';
+import { resolveColorScheme, getThemeFont } from '../utils/themeUtils.js';
 import { createAccentLayers, getAccentLayout, adjustY, DEFAULT_LAYOUT } from './accentImage.js';
 import { createBackgroundLayer } from './captionUtils.js';
 
@@ -50,6 +50,7 @@ export function statHighlight(input: StatHighlightInput, context: TemplateContex
       text: stat,
       style: {
         fontSize: statFontSize,
+        fontFamily: getThemeFont(context, 'title'),
         fontWeight: 'bold',
         color: colors.text,
         shadow: !!accentImage,
@@ -71,6 +72,7 @@ export function statHighlight(input: StatHighlightInput, context: TemplateContex
       text: description,
       style: {
         fontSize: descFontSize,
+        fontFamily: getThemeFont(context, 'body'),
         color: theme.colors.textMuted,
         textAlign: 'center',
         lineHeight: 1.6,
@@ -95,6 +97,7 @@ export function statHighlight(input: StatHighlightInput, context: TemplateContex
         text: detail,
         style: {
           fontSize: detailFontSize,
+          fontFamily: getThemeFont(context, 'body'),
           color: colors.accent,
           textAlign: 'center',
           shadow: !!accentImage,

package/src/doc/templates/titleBlock.ts

@@ -11,6 +11,7 @@
 import type { Layer } from '../../schemas/Doc.js';
 import type { TitleBlockInput, TemplateContext } from '../../schemas/BlockTemplates.js';
 import { scaledFontSize } from '../../schemas/BlockTemplates.js';
+import { getThemeFont } from '../utils/themeUtils.js';
 
 export function titleBlock(input: TitleBlockInput, context: TemplateContext): Layer[] {
   const { title, subtitle, backgroundColor } = input;
@@ -56,6 +57,7 @@ export function titleBlock(input: TitleBlockInput, context: TemplateContext): La
         text: title,
         style: {
           fontSize: titleFontSize,
+          fontFamily: getThemeFont(context, 'title'),
           fontWeight: 'bold',
           color: theme.colors.text,
           textAlign: 'center',
@@ -81,6 +83,7 @@ export function titleBlock(input: TitleBlockInput, context: TemplateContext): La
         text: subtitle,
         style: {
           fontSize: subtitleFontSize,
+          fontFamily: getThemeFont(context, 'body'),
           color: theme.colors.textMuted,
           textAlign: 'center',
           lineHeight: 1.5,

package/src/doc/templates/twoColumn.ts

@@ -13,7 +13,7 @@
 import type { Layer } from '../../schemas/Doc.js';
 import type { TwoColumnInput, TemplateContext } from '../../schemas/BlockTemplates.js';
 import { scaledFontSize } from '../../schemas/BlockTemplates.js';
-import { resolveColorScheme } from '../utils/themeUtils.js';
+import { resolveColorScheme, getThemeFont } from '../utils/themeUtils.js';
 import { getTwoColumnPositions } from '../../schemas/LayoutStrategy.js';
 
 export function twoColumn(input: TwoColumnInput, context: TemplateContext): Layer[] {
@@ -87,6 +87,7 @@ export function twoColumn(input: TwoColumnInput, context: TemplateContext): Laye
         text: header,
         style: {
           fontSize: headerFontSize,
+          fontFamily: getThemeFont(context, 'title'),
           color: theme.colors.textMuted,
           textAlign: 'center',
         },
@@ -126,6 +127,7 @@ export function twoColumn(input: TwoColumnInput, context: TemplateContext): Laye
       text: left.label,
       style: {
         fontSize: labelFontSize,
+        fontFamily: getThemeFont(context, 'body'),
         fontWeight: 'bold',
         color: leftColors.text,
         textAlign: 'center',
@@ -149,6 +151,7 @@ export function twoColumn(input: TwoColumnInput, context: TemplateContext): Laye
         text: left.sublabel,
         style: {
           fontSize: sublabelFontSize,
+          fontFamily: getThemeFont(context, 'body'),
           color: theme.colors.textMuted,
           textAlign: 'center',
           lineHeight: 1.4,
@@ -176,6 +179,7 @@ export function twoColumn(input: TwoColumnInput, context: TemplateContext): Laye
       text: connectorSymbol,
       style: {
         fontSize: connectorFontSize,
+        fontFamily: getThemeFont(context, 'title'),
         fontWeight: 'bold',
         color: 'rgba(255, 255, 255, 0.6)',
         textAlign: 'center',
@@ -197,6 +201,7 @@ export function twoColumn(input: TwoColumnInput, context: TemplateContext): Laye
       text: right.label,
       style: {
         fontSize: labelFontSize,
+        fontFamily: getThemeFont(context, 'body'),
         fontWeight: 'bold',
         color: rightColors.text,
         textAlign: 'center',
@@ -220,6 +225,7 @@ export function twoColumn(input: TwoColumnInput, context: TemplateContext): Laye
         text: right.sublabel,
         style: {
           fontSize: sublabelFontSize,
+          fontFamily: getThemeFont(context, 'body'),
           color: theme.colors.textMuted,
           textAlign: 'center',
           lineHeight: 1.4,

package/src/doc/templates/videoPullQuote.ts

@@ -18,6 +18,7 @@
 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';
 
 export function videoPullQuote(input: VideoPullQuoteInput, context: TemplateContext): Layer[] {
   const { text, attribution, backgroundVideo } = input;
@@ -66,6 +67,7 @@ export function videoPullQuote(input: VideoPullQuoteInput, context: TemplateCont
         text: '\u201C',
         style: {
           fontSize: decoFontSize,
+          fontFamily: getThemeFont(context, 'title'),
           color: 'rgba(255, 255, 255, 0.08)',
           textAlign: 'center',
         },
@@ -85,6 +87,7 @@ export function videoPullQuote(input: VideoPullQuoteInput, context: TemplateCont
         text,
         style: {
           fontSize: quoteFontSize,
+          fontFamily: getThemeFont(context, 'title'),
           color: '#ffffff',
           textAlign: 'center',
           lineHeight: 1.5,
@@ -110,6 +113,7 @@ export function videoPullQuote(input: VideoPullQuoteInput, context: TemplateCont
         text: `\u2014 ${attribution}`,
         style: {
           fontSize: attrFontSize,
+          fontFamily: getThemeFont(context, 'body'),
           color: 'rgba(255, 255, 255, 0.7)',
           textAlign: 'center',
           shadow: true,

package/src/doc/templates/videoWithCaption.ts

@@ -18,6 +18,7 @@
 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 { cleanCaption } from './captionUtils.js';
 
 export function videoWithCaption(input: VideoWithCaptionInput, context: TemplateContext): Layer[] {
@@ -86,6 +87,7 @@ export function videoWithCaption(input: VideoWithCaptionInput, context: Template
         text: caption,
         style: {
           fontSize: captionFontSize,
+          fontFamily: getThemeFont(context, 'body'),
           color: theme.colors.text,
           textAlign: 'center',
           shadow: true,
@@ -110,6 +112,7 @@ export function videoWithCaption(input: VideoWithCaptionInput, context: Template
         text: videoCredit,
         style: {
           fontSize: creditFontSize,
+          fontFamily: getThemeFont(context, 'body'),
           color: 'rgba(255, 255, 255, 0.5)',
           textAlign: 'right',
         },

package/src/doc/utils/themeUtils.ts

@@ -37,6 +37,35 @@ export function resolveColorScheme(
   return FALLBACK_COLOR_SCHEME;
 }
 
+// ============================================
+// Font Family Resolution
+// ============================================
+
+/** Safe system font fallbacks. */
+const FALLBACK_BODY = 'system-ui, -apple-system, "Segoe UI", Roboto, sans-serif';
+const FALLBACK_TITLE = 'Georgia, "Times New Roman", serif';
+const FALLBACK_MONO = 'Consolas, "Courier New", monospace';
+
+/**
+ * Get the theme font family for a given role.
+ * Templates call this to set `fontFamily` on text layers.
+ *
+ * @param context Template context (includes theme with typography settings)
+ * @param role    'title' for headings, 'body' for descriptions, 'mono' for code
+ * @returns A CSS font-family string with the theme's font and safe fallbacks
+ */
+export function getThemeFont(context: TemplateContext, role: 'title' | 'body' | 'mono'): string {
+  const { typography } = context.theme;
+  switch (role) {
+    case 'title':
+      return typography.titleFontFamily || FALLBACK_TITLE;
+    case 'body':
+      return typography.bodyFontFamily || FALLBACK_BODY;
+    case 'mono':
+      return typography.monoFontFamily || FALLBACK_MONO;
+  }
+}
+
 // ============================================
 // Font Sizing
 // ============================================

package/src/markdown/convert.ts

@@ -181,17 +181,25 @@ function extractTemplateAnnotation(
  */
 function parseAnnotationTokens(inner: string): HeadingTemplateAnnotation {
   const tokens = inner.split(/\s+/);
-  const template = tokens[0];
   const params: Record<string, string> = {};
 
-  for (let i = 1; i < tokens.length; i++) {
+  // If the first token contains '=', there's no template name —
+  // the annotation is purely key-value (e.g., `{[audio=intro.mp3]}`).
+  const firstIsParam = tokens[0].indexOf('=') > 0;
+  const template = firstIsParam ? undefined : tokens[0];
+  const startIdx = firstIsParam ? 0 : 1;
+
+  for (let i = startIdx; i < tokens.length; i++) {
     const eqIdx = tokens[i].indexOf('=');
     if (eqIdx > 0) {
       params[tokens[i].slice(0, eqIdx)] = tokens[i].slice(eqIdx + 1);
     }
   }
 
-  const result: HeadingTemplateAnnotation = { template };
+  const result: HeadingTemplateAnnotation = {};
+  if (template) {
+    result.template = template;
+  }
   if (Object.keys(params).length > 0) {
     result.params = params;
   }
@@ -202,14 +210,16 @@ function parseAnnotationTokens(inner: string): HeadingTemplateAnnotation {
  * Serialize a HeadingTemplateAnnotation back to `{[templateName key=value …]}` text.
  */
 function serializeTemplateAnnotation(annotation: HeadingTemplateAnnotation): string {
-  let result = `{[${annotation.template}`;
+  const parts: string[] = [];
+  if (annotation.template) {
+    parts.push(annotation.template);
+  }
   if (annotation.params) {
     for (const [key, value] of Object.entries(annotation.params)) {
-      result += ` ${key}=${value}`;
+      parts.push(`${key}=${value}`);
     }
   }
-  result += ']}';
-  return result;
+  return `{[${parts.join(' ')}]}`;
 }
 
 /**

package/src/markdown/types.ts

@@ -118,8 +118,10 @@ interface MarkdownNodeBase {
  * → `{ template: 'chart', params: { colorScheme: 'blue' } }`
  */
 export interface HeadingTemplateAnnotation {
-  /** Template name (first token inside `{[…]}`) */
-  template: string;
+  /** Template name (first token inside `{[…]}`).
+   *  Optional when the annotation contains only key=value pairs
+   *  (e.g., `{[audio=intro.mp3]}`). */
+  template?: string;
   /** Optional key-value parameters (remaining `key=value` tokens) */
   params?: Record<string, string>;
 }

package/src/schemas/BlockTemplates.ts

@@ -39,12 +39,12 @@ export type ColorScheme = string;
  * PT Serif provides a classic, readable appearance for documentary-style content.
  * Used as a fallback in TextLayer when no font is specified.
  */
-export const DEFAULT_DOC_FONT = '"PT Serif", Georgia, "Times New Roman", serif';
+export const DEFAULT_DOC_FONT = 'system-ui, -apple-system, "Segoe UI", Roboto, sans-serif';
 
 /**
  * Default font family for titles.
  */
-export const DEFAULT_TITLE_FONT = '"PT Serif", Georgia, "Times New Roman", serif';
+export const DEFAULT_TITLE_FONT = 'Georgia, "Times New Roman", serif';
 
 // ============================================
 // Accent Image System

package/src/schemas/Doc.ts

@@ -127,6 +127,13 @@ export interface Block {
   /** Template name that generated this block (for debugging) */
   template?: string;
 
+  /**
+   * Display title for template rendering.
+   * Extracted from the sourceHeading when the block is created by markdownToDoc().
+   * Templates like sectionHeader and titleBlock read this for their title layer.
+   */
+  title?: string;
+
   // ── Markdown-driven hierarchy (optional) ──
 
   /**
@@ -436,6 +443,19 @@ export interface AudioTrack {
 // Captions
 // ============================================
 
+/**
+ * A single word with precise timing, used for word-level highlighting
+ * in social-style captions. Populated from TTS timing data when available.
+ */
+export interface CaptionWord {
+  /** The word text */
+  text: string;
+  /** Start time in seconds (relative to doc start) */
+  startTime: number;
+  /** End time in seconds */
+  endTime: number;
+}
+
 /**
  * A single caption phrase to display during playback.
  */
@@ -448,6 +468,13 @@ export interface CaptionPhrase {
   endTime: number;
   /** Which audio segment this caption belongs to (0-indexed) */
   audioSegment: number;
+  /**
+   * Optional per-word timing from TTS timing data.
+   * When present, enables precise word-level highlighting in social
+   * caption style. When absent, word timing is interpolated evenly
+   * across the phrase duration.
+   */
+  words?: CaptionWord[];
 }
 
 /**
@@ -476,6 +503,39 @@ export interface AudioSegment {
   startTime: number;
 }
 
+// ============================================
+// Audio Timing Data (from TTS)
+// ============================================
+
+/**
+ * A single word-level timing bookmark from TTS synthesis.
+ * Used for precise audio-to-content mapping and word-level caption sync.
+ */
+export interface AudioBookmark {
+  /** Unique identifier (e.g., "word-0", "word-1") */
+  id: string;
+  /** Timestamp in seconds from audio start */
+  time: number;
+  /** Character offset in the source text */
+  charOffset: number;
+  /** The word text at this position */
+  textFragment?: string;
+}
+
+/**
+ * Timing data for an audio segment, typically from a `.timing.json` file
+ * generated alongside TTS audio. Contains the source text and per-word
+ * timing bookmarks for precise content matching and caption sync.
+ */
+export interface AudioTimingData {
+  /** The normalized plain text that was synthesized */
+  sourceText: string;
+  /** Word-level timing bookmarks */
+  bookmarks: AudioBookmark[];
+  /** Total audio duration in seconds */
+  duration: number;
+}
+
 // ============================================
 // Helper Functions
 // ============================================