@bendyline/squisq 1.2.1 → 1.3.0

package/src/__tests__/markdown.test.ts

@@ -33,6 +33,7 @@ import type {
   MarkdownLinkReference,
   MarkdownImageReference,
   MarkdownText,
+  MarkdownMention,
 } from '../markdown/index';
 
 // ============================================
@@ -151,6 +152,49 @@ describe('parseMarkdown / stringifyMarkdown', () => {
       expect(link.children[0]).toEqual({ type: 'text', value: 'Click here' });
     });
 
+    it('parses mentions from @[Name](scheme:id)', () => {
+      const doc = parse('Hey @[Leo](gezel:leo), take a look.');
+      const p = doc.children[0] as MarkdownParagraph;
+      const text0 = p.children[0] as MarkdownText;
+      expect(text0).toEqual({ type: 'text', value: 'Hey ' });
+      const mention = p.children[1] as MarkdownMention;
+      expect(mention).toEqual({
+        type: 'mention',
+        targetKind: 'gezel',
+        targetId: 'leo',
+        displayName: 'Leo',
+      });
+      const text2 = p.children[2] as MarkdownText;
+      expect(text2.value).toBe(', take a look.');
+    });
+
+    it('round-trips a mention back to markdown', () => {
+      // remark-stringify escapes `:` in link URLs that follow an `@` (to
+      // disambiguate from autolink syntax). The escape is idempotent —
+      // re-parsing `\:` produces the unescaped url, so the round-trip
+      // preserves the mention semantically even if the raw text changes
+      // on the first pass.
+      const input = 'Hey @[Leo](gezel:leo), ping @[Tess](gezel:tess) too.\n';
+      const once = stringifyMarkdown(parseMarkdown(input));
+      const twice = stringifyMarkdown(parseMarkdown(once));
+      expect(twice).toBe(once);
+      // Semantics are preserved: re-parsing yields mentions.
+      const doc = parseMarkdown(once) as MarkdownDocument;
+      const p = doc.children[0] as MarkdownParagraph;
+      const m1 = p.children.find((c) => c.type === 'mention') as MarkdownMention;
+      expect(m1.targetKind).toBe('gezel');
+      expect(m1.targetId).toBe('leo');
+      expect(m1.displayName).toBe('Leo');
+    });
+
+    it('does not collapse @ + link when the url has no scheme', () => {
+      const doc = parse('Cost @[100]($100)');
+      const p = doc.children[0] as MarkdownParagraph;
+      // "$100" doesn't match scheme:id because $ isn't a scheme character
+      // → stays as text("Cost @") + link
+      expect((p.children[1] as MarkdownLink).type).toBe('link');
+    });
+
     it('parses images', () => {
       const doc = parse('![Alt text](image.png "Image title")');
       const p = doc.children[0] as MarkdownParagraph;
@@ -591,6 +635,28 @@ describe('Tree utilities', () => {
     expect(extractPlainText(doc)).toBe('TitleHello world');
   });
 
+  it('extractPlainText preserves list item boundaries', () => {
+    const list: MarkdownList = {
+      type: 'list',
+      ordered: false,
+      children: [
+        {
+          type: 'listItem',
+          children: [{ type: 'paragraph', children: [{ type: 'text', value: 'Apple' }] }],
+        },
+        {
+          type: 'listItem',
+          children: [{ type: 'paragraph', children: [{ type: 'text', value: 'Banana' }] }],
+        },
+        {
+          type: 'listItem',
+          children: [{ type: 'paragraph', children: [{ type: 'text', value: 'Cherry' }] }],
+        },
+      ],
+    };
+    expect(extractPlainText(list)).toBe('Apple\nBanana\nCherry');
+  });
+
   it('countNodes counts all nodes', () => {
     expect(countNodes(doc)).toBe(7); // document + heading + text + paragraph + text + link + text
   });

package/src/__tests__/markdownToDoc.test.ts

@@ -468,3 +468,83 @@ describe('caption generation', () => {
     }
   });
 });
+
+// ============================================
+// Auto cover block (startBlock) generation
+// ============================================
+
+describe('auto cover block generation', () => {
+  it('creates startBlock from H1 title', () => {
+    const md = parseMarkdown('# My Great Article\n\nSome introduction text.');
+    const doc = markdownToDoc(md);
+
+    expect(doc.startBlock).toBeDefined();
+    expect(doc.startBlock!.title).toBe('My Great Article');
+  });
+
+  it('uses first paragraph after H1 as subtitle', () => {
+    const md = parseMarkdown('# Title\n\nThis is a subtitle paragraph.\n\n## Section\n\nBody');
+    const doc = markdownToDoc(md);
+
+    expect(doc.startBlock).toBeDefined();
+    expect(doc.startBlock!.subtitle).toBe('This is a subtitle paragraph.');
+  });
+
+  it('picks first image as heroSrc', () => {
+    const md = parseMarkdown('# Title\n\n![photo](hero.jpg)\n\nSome text.');
+    const doc = markdownToDoc(md);
+
+    expect(doc.startBlock).toBeDefined();
+    expect(doc.startBlock!.heroSrc).toBe('hero.jpg');
+    expect(doc.startBlock!.heroAlt).toBe('photo');
+  });
+
+  it('picks image from deeper in document', () => {
+    const md = parseMarkdown(
+      '# Title\n\nIntro text.\n\n## Section\n\nBody text.\n\n![deep pic](deep.png)',
+    );
+    const doc = markdownToDoc(md);
+
+    expect(doc.startBlock).toBeDefined();
+    expect(doc.startBlock!.heroSrc).toBe('deep.png');
+  });
+
+  it('works without images (no heroSrc)', () => {
+    const md = parseMarkdown('# Title\n\nPlain text, no images.');
+    const doc = markdownToDoc(md);
+
+    expect(doc.startBlock).toBeDefined();
+    expect(doc.startBlock!.title).toBe('Title');
+    expect(doc.startBlock!.heroSrc).toBeUndefined();
+  });
+
+  it('sets ambientMotion to zoomIn by default', () => {
+    const md = parseMarkdown('# Title\n\nContent.');
+    const doc = markdownToDoc(md);
+
+    expect(doc.startBlock!.ambientMotion).toBe('zoomIn');
+  });
+
+  it('does not create startBlock when no H1 exists', () => {
+    const md = parseMarkdown('## Section A\n\nText A\n\n## Section B\n\nText B');
+    const doc = markdownToDoc(md);
+
+    expect(doc.startBlock).toBeUndefined();
+  });
+
+  it('does not create startBlock when generateCoverBlock is false', () => {
+    const md = parseMarkdown('# Title\n\nContent.');
+    const doc = markdownToDoc(md, { generateCoverBlock: false });
+
+    expect(doc.startBlock).toBeUndefined();
+  });
+
+  it('does not create startBlock for heading-only document with no content', () => {
+    const md = parseMarkdown('# Title');
+    const doc = markdownToDoc(md);
+
+    expect(doc.startBlock).toBeDefined();
+    expect(doc.startBlock!.title).toBe('Title');
+    expect(doc.startBlock!.subtitle).toBeUndefined();
+  });
+});

package/src/__tests__/surface.test.ts

@@ -0,0 +1,68 @@
+import { describe, it, expect } from 'vitest';
+import {
+  applySurface,
+  DARK_SURFACE,
+  DEFAULT_THEME,
+  LIGHT_SURFACE,
+  type SurfaceScheme,
+} from '../schemas/index.js';
+
+describe('SurfaceScheme', () => {
+  it('LIGHT_SURFACE and DARK_SURFACE expose the full field set', () => {
+    for (const s of [LIGHT_SURFACE, DARK_SURFACE]) {
+      expect(typeof s.id).toBe('string');
+      expect(typeof s.background).toBe('string');
+      expect(typeof s.backgroundLight).toBe('string');
+      expect(typeof s.text).toBe('string');
+      expect(typeof s.textMuted).toBe('string');
+    }
+  });
+});
+
+describe('applySurface', () => {
+  it('overlays surface fields onto a theme', () => {
+    const out = applySurface(DEFAULT_THEME, LIGHT_SURFACE);
+    expect(out.colors.background).toBe(LIGHT_SURFACE.background);
+    expect(out.colors.backgroundLight).toBe(LIGHT_SURFACE.backgroundLight);
+    expect(out.colors.text).toBe(LIGHT_SURFACE.text);
+    expect(out.colors.textMuted).toBe(LIGHT_SURFACE.textMuted);
+  });
+
+  it('leaves editorial colors (primary, highlight, warning) untouched', () => {
+    const out = applySurface(DEFAULT_THEME, DARK_SURFACE);
+    expect(out.colors.primary).toBe(DEFAULT_THEME.colors.primary);
+    expect(out.colors.secondary).toBe(DEFAULT_THEME.colors.secondary);
+    expect(out.colors.highlight).toBe(DEFAULT_THEME.colors.highlight);
+    expect(out.colors.warning).toBe(DEFAULT_THEME.colors.warning);
+  });
+
+  it('leaves typography, style, renderStyle, colorSchemes untouched', () => {
+    const out = applySurface(DEFAULT_THEME, LIGHT_SURFACE);
+    expect(out.typography).toBe(DEFAULT_THEME.typography);
+    expect(out.style).toBe(DEFAULT_THEME.style);
+    expect(out.renderStyle).toBe(DEFAULT_THEME.renderStyle);
+    expect(out.colorSchemes).toBe(DEFAULT_THEME.colorSchemes);
+  });
+
+  it('returns a new theme (does not mutate the base)', () => {
+    const frozenTheme = DEFAULT_THEME;
+    const originalBg = frozenTheme.colors.background;
+    const out = applySurface(frozenTheme, DARK_SURFACE);
+    expect(out).not.toBe(frozenTheme);
+    expect(out.colors).not.toBe(frozenTheme.colors);
+    expect(frozenTheme.colors.background).toBe(originalBg);
+  });
+
+  it('accepts custom SurfaceScheme objects', () => {
+    const custom: SurfaceScheme = {
+      id: 'parchment',
+      background: '#f4ecd8',
+      backgroundLight: '#e8dfc4',
+      text: '#2b2b2b',
+      textMuted: '#6b6b6b',
+    };
+    const out = applySurface(DEFAULT_THEME, custom);
+    expect(out.colors.background).toBe('#f4ecd8');
+    expect(out.colors.textMuted).toBe('#6b6b6b');
+  });
+});

package/src/doc/audioMapping.ts

@@ -124,23 +124,61 @@ interface Mp3Info {
 
 // ── Core Functions ───────────────────────────────────────────────────
 
+/**
+ * Parse a consolidated timing.json (version 2) which contains all section
+ * timing data in a single file.
+ */
+function parseConsolidatedTiming(data: ArrayBuffer): Record<string, AudioTimingData> | null {
+  try {
+    const text = new TextDecoder().decode(data);
+    const parsed = JSON.parse(text);
+    if (parsed && parsed.version === 2 && parsed.sections) {
+      return parsed.sections as Record<string, AudioTimingData>;
+    }
+    return null;
+  } catch {
+    return null;
+  }
+}
+
 /**
  * Discover all MP3 files in a container and load their timing data.
+ * Checks for a consolidated timing.json first, then falls back to per-file .timing.json.
  */
 async function discoverMp3s(container: ContentContainer): Promise<Mp3Info[]> {
   const files = await container.listFiles();
   const mp3Files = files.filter((f) => f.path.endsWith('.mp3'));
   const results: Mp3Info[] = [];
 
+  // Try to load consolidated timing.json
+  let consolidatedSections: Record<string, AudioTimingData> | null = null;
+  const consolidatedData = await container.readFile('timing.json');
+  if (consolidatedData) {
+    consolidatedSections = parseConsolidatedTiming(consolidatedData);
+  }
+
   for (const file of mp3Files) {
     const filename = file.path.split('/').pop() ?? file.path;
     let timing: AudioTimingData | null = null;
 
-    // Try to load timing.json
-    const timingPath = `${file.path}.timing.json`;
-    const timingData = await container.readFile(timingPath);
-    if (timingData) {
-      timing = parseTimingJson(timingData);
+    // Try consolidated timing first: match section name from filename
+    if (consolidatedSections) {
+      const mp3Base = filename.replace(/\.mp3$/, '');
+      for (const [sectionName, sectionTiming] of Object.entries(consolidatedSections)) {
+        if (mp3Base.endsWith(`-${sectionName}`)) {
+          timing = sectionTiming;
+          break;
+        }
+      }
+    }
+
+    // Fall back to per-file .timing.json
+    if (!timing) {
+      const timingPath = `${file.path}.timing.json`;
+      const timingData = await container.readFile(timingPath);
+      if (timingData) {
+        timing = parseTimingJson(timingData);
+      }
     }
 
     results.push({ path: file.path, filename, timing });

package/src/doc/markdownToDoc.ts

@@ -22,8 +22,14 @@
  * ```
  */
 
-import type { Doc, Block, CaptionTrack, CaptionPhrase } from '../schemas/Doc.js';
-import type { MarkdownDocument, MarkdownBlockNode, MarkdownHeading } from '../markdown/types.js';
+import type { Doc, Block, CaptionTrack, CaptionPhrase, StartBlockConfig } from '../schemas/Doc.js';
+import type {
+  MarkdownDocument,
+  MarkdownBlockNode,
+  MarkdownHeading,
+  MarkdownNode,
+  MarkdownImage,
+} from '../markdown/types.js';
 import { extractPlainText } from '../markdown/utils.js';
 import { estimateReadingTime } from '../timing/readingTime.js';
 
@@ -46,6 +52,14 @@ export interface MarkdownToDocOptions {
 
   /** Custom ID generator. Receives the heading node and its index. */
   generateId?: (heading: MarkdownHeading, index: number) => string;
+
+  /**
+   * Whether to auto-generate a cover startBlock from the first H1 heading.
+   * When true (default), a StartBlockConfig is created using the first H1's
+   * text as the title. If the document contains an image, the first image
+   * is used as the hero. Set to false to suppress automatic cover generation.
+   */
+  generateCoverBlock?: boolean;
 }
 
 // ============================================
@@ -267,7 +281,7 @@ export function markdownToDoc(markdownDoc: MarkdownDocument, options?: MarkdownT
   const captions: CaptionTrack | undefined =
     phrases.length > 0 ? { phrases, generatedAt: new Date().toISOString(), version: 1 } : undefined;
 
-  return {
+  const doc: Doc = {
     articleId,
     duration: currentTime,
     blocks: rootBlocks,
@@ -277,6 +291,16 @@ export function markdownToDoc(markdownDoc: MarkdownDocument, options?: MarkdownT
     ...(captions ? { captions } : {}),
     ...(markdownDoc.frontmatter ? { frontmatter: markdownDoc.frontmatter } : {}),
   };
+
+  // Auto-generate cover startBlock from the first H1 heading
+  if (options?.generateCoverBlock ?? true) {
+    const coverConfig = buildStartBlock(markdownDoc, rootBlocks);
+    if (coverConfig) {
+      doc.startBlock = coverConfig;
+    }
+  }
+
+  return doc;
 }
 
 // ============================================
@@ -409,3 +433,50 @@ function splitIntoSentences(text: string): string[] {
   }
   return merged;
 }
+
+/**
+ * Walk a MarkdownNode tree depth-first to find the first image node.
+ * Returns the MarkdownImage or undefined if none found.
+ */
+function findFirstImage(node: MarkdownNode): MarkdownImage | undefined {
+  if (node.type === 'image') return node as MarkdownImage;
+  if ('children' in node && Array.isArray((node as { children?: unknown[] }).children)) {
+    for (const child of (node as { children: MarkdownNode[] }).children) {
+      const found = findFirstImage(child);
+      if (found) return found;
+    }
+  }
+  return undefined;
+}
+
+/**
+ * Build a StartBlockConfig from the document's first H1 heading and optional
+ * first image. Returns undefined if the document has no H1 heading.
+ */
+function buildStartBlock(
+  markdownDoc: MarkdownDocument,
+  rootBlocks: Block[],
+): StartBlockConfig | undefined {
+  // Find the first H1 block — it provides the cover title
+  const firstH1 = rootBlocks.find((b) => b.sourceHeading?.depth === 1);
+  if (!firstH1) return undefined;
+
+  const title = firstH1.title ?? extractPlainText(firstH1.sourceHeading!);
+  if (!title) return undefined;
+
+  // Look for the first paragraph immediately after the H1 to use as subtitle
+  const subtitle =
+    firstH1.contents?.[0]?.type === 'paragraph' ? extractPlainText(firstH1.contents[0]) : undefined;
+
+  // Scan the whole document for the first image to use as the hero
+  const firstImage = findFirstImage(markdownDoc);
+
+  const config: StartBlockConfig = {
+    title,
+    ...(subtitle ? { subtitle } : {}),
+    ...(firstImage ? { heroSrc: firstImage.url, heroAlt: firstImage.alt ?? title } : {}),
+    ambientMotion: 'zoomIn',
+  };
+
+  return config;
+}

package/src/doc/templates/coverBlock.ts

@@ -25,8 +25,8 @@ import { mapAmbientMotion } from './accentImage.js';
  * Input for coverBlock template - matches StartBlockConfig
  */
 export interface CoverBlockInput {
-  /** Path to hero image */
-  heroSrc: string;
+  /** Path to hero image (omit for theme-driven background) */
+  heroSrc?: string;
   /** Alt text for the hero image */
   heroAlt?: string;
   /** Title to display over the hero */
@@ -48,63 +48,93 @@ 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 - use larger sizes for the cover
-  const titleFontSize = scaledFontSize(96, context, true);
-  const subtitleFontSize = scaledFontSize(36, context, false);
+  // Scale font sizes for viewport - cover titles are larger than regular title blocks
+  const titleFontSize = scaledFontSize(120, context, true);
+  const subtitleFontSize = scaledFontSize(40, context, false);
 
-  // Determine Ken Burns animation
-  const imageAnimation = mapAmbientMotion(ambientMotion);
+  const layers: Layer[] = [];
 
-  const layers: Layer[] = [
-    // Full-screen hero image
-    {
-      type: 'image',
-      id: 'cover-hero',
-      content: {
-        src: heroSrc,
-        alt: heroAlt || title,
-        fit: 'cover',
-        credit: heroCredit,
-        license: heroLicense,
+  if (heroSrc) {
+    // Hero image path: full-screen image with gradient overlay for text readability
+    const imageAnimation = mapAmbientMotion(ambientMotion);
+
+    layers.push(
+      {
+        type: 'image',
+        id: 'cover-hero',
+        content: {
+          src: heroSrc,
+          alt: heroAlt || title,
+          fit: 'cover',
+          credit: heroCredit,
+          license: heroLicense,
+        },
+        position: { x: 0, y: 0, width: '100%', height: '100%' },
+        animation: imageAnimation,
       },
-      position: { x: 0, y: 0, width: '100%', height: '100%' },
-      animation: imageAnimation,
-    },
-    // Gradient overlay for text readability - from bottom
-    {
+      {
+        type: 'shape',
+        id: 'cover-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%)',
+        },
+        position: { x: 0, y: 0, width: '100%', height: '100%' },
+      },
+    );
+  } else {
+    // No hero image: use a rich theme-driven background with radial gradient
+    layers.push({
       type: 'shape',
-      id: 'cover-gradient',
+      id: 'cover-bg',
       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: `radial-gradient(ellipse at 50% 40%, ${theme.colors.primary} 0%, ${theme.colors.background} 100%)`,
       },
       position: { x: 0, y: 0, width: '100%', height: '100%' },
-    },
-    // Title - positioned lower in the frame to work with hero composition
-    {
-      type: 'text',
-      id: 'cover-title',
+    });
+
+    // Subtle decorative accent line below title
+    layers.push({
+      type: 'shape',
+      id: 'cover-accent',
       content: {
-        text: title,
-        style: {
-          fontSize: titleFontSize,
-          fontFamily: getThemeFont(context, 'title'),
-          fontWeight: 'bold',
-          color: theme.colors.text,
-          textAlign: 'center',
-          shadow: true,
-        },
+        shape: 'rect',
+        fill: 'rgba(255, 255, 255, 0.2)',
       },
       position: {
-        x: '50%',
-        y: subtitle ? '70%' : '75%',
-        anchor: 'center',
-        width: layout.maxTextWidth,
+        x: '35%',
+        y: subtitle ? '42%' : '58%',
+        width: '30%',
+        height: '2px',
+      },
+    });
+  }
+
+  // Title - positioned lower when over hero, centered when over solid background
+  layers.push({
+    type: 'text',
+    id: 'cover-title',
+    content: {
+      text: title,
+      style: {
+        fontSize: titleFontSize,
+        fontFamily: getThemeFont(context, 'title'),
+        fontWeight: 'bold',
+        color: theme.colors.text,
+        textAlign: 'center',
+        shadow: true,
       },
-      // No animation delay - shown immediately at rest
-      animation: { type: 'fadeIn', duration: 0.8 },
     },
-  ];
+    position: {
+      x: '50%',
+      y: heroSrc ? (subtitle ? '70%' : '75%') : subtitle ? layout.primaryY : '50%',
+      anchor: 'center',
+      width: layout.maxTextWidth,
+    },
+    // No animation delay - shown immediately at rest
+    animation: { type: 'fadeIn', duration: 0.8 },
+  });
 
   // Add subtitle if provided
   if (subtitle) {
@@ -123,7 +153,7 @@ export function coverBlock(input: CoverBlockInput, context: TemplateContext): La
       },
       position: {
         x: '50%',
-        y: '82%',
+        y: heroSrc ? '82%' : layout.secondaryY,
         anchor: 'center',
         width: layout.maxTextWidth,
       },