@bendyline/squisq 1.2.0 → 1.2.2

package/dist/storage/ContentContainer.js

@@ -46,7 +46,16 @@ export class MemoryContentContainer {
         return this.files.get(path)?.data ?? null;
     }
     async writeFile(path, data, mimeType) {
-        const buffer = data instanceof ArrayBuffer ? data : data.slice().buffer;
+        // Copy to a standalone ArrayBuffer. Uint8Array/Buffer may share a larger
+        // backing buffer (e.g., Node's buffer pool), so we must slice to the
+        // exact byte range to avoid storing stale pool data.
+        let buffer;
+        if (data instanceof ArrayBuffer) {
+            buffer = data;
+        }
+        else {
+            buffer = data.buffer.slice(data.byteOffset, data.byteOffset + data.byteLength);
+        }
         this.files.set(path, {
             data: buffer,
             mimeType: mimeType ?? guessMimeType(path),

package/dist/storage/ContentContainer.js.map

@@ -1 +1 @@
-{"version":3,"file":"ContentContainer.js","sourceRoot":"","sources":["../../src/storage/ContentContainer.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"ContentContainer.js","sourceRoot":"","sources":["../../src/storage/ContentContainer.ts"],"names":[],"mappings":"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"}

package/dist/story/index.d.ts

@@ -1,8 +1,8 @@
-import { H as PersistentLayer, L as Layer, J as PersistentLayerConfig, ac as TitleBlockInput, a2 as TemplateContext, W as SectionHeaderInput, _ as StatHighlightInput, U as QuoteBlockInput, F as FactCardInput, ag as TwoColumnInput, o as DateEventInput, v as ImageWithCaptionInput, M as MapBlockInput, Z as StartBlockConfig, t as FullBleedQuoteInput, x as ListBlockInput, Q as PhotoGridInput, q as DefinitionCardInput, k as ComparisonBarInput, T as PullQuoteInput, ak as VideoWithCaptionInput, aj as VideoPullQuoteInput, n as DataTableInput, A as AccentImage, a as AccentPosition, a7 as Theme, al as ViewportConfig, s as DocBlock, B as Block, a1 as TemplateBlock, a4 as TemplateRegistry, b as Animation, c as AnimationType, af as TransitionType, a9 as ThemeColorScheme, r as Doc } from '../Doc-Dwn5aHFC.js';
-export { w as LayoutHints, V as RenderStyle, a8 as ThemeColorPalette, aa as ThemeStyle, ab as ThemeTypography, ah as VIEWPORT_PRESETS, am as ViewportOrientation, an as ViewportPreset, aq as createTemplateContext, av as getLayoutHints, ay as getTwoColumnPositions, az as getViewport, aA as getViewportOrientation, aC as isTemplateBlock, aE as scaledFontSize } from '../Doc-Dwn5aHFC.js';
+import { H as PersistentLayer, L as Layer, J as PersistentLayerConfig, ac as TitleBlockInput, a2 as TemplateContext, W as SectionHeaderInput, _ as StatHighlightInput, U as QuoteBlockInput, F as FactCardInput, ag as TwoColumnInput, o as DateEventInput, v as ImageWithCaptionInput, M as MapBlockInput, Z as StartBlockConfig, t as FullBleedQuoteInput, x as ListBlockInput, Q as PhotoGridInput, q as DefinitionCardInput, k as ComparisonBarInput, T as PullQuoteInput, ak as VideoWithCaptionInput, aj as VideoPullQuoteInput, n as DataTableInput, A as AccentImage, a as AccentPosition, a7 as Theme, al as ViewportConfig, s as DocBlock, B as Block, a1 as TemplateBlock, a4 as TemplateRegistry, b as Animation, c as AnimationType, af as TransitionType, a9 as ThemeColorScheme, r as Doc } from '../Doc-BfBhiCNr.js';
+export { w as LayoutHints, V as RenderStyle, a8 as ThemeColorPalette, aa as ThemeStyle, ab as ThemeTypography, ah as VIEWPORT_PRESETS, am as ViewportOrientation, an as ViewportPreset, aq as createTemplateContext, av as getLayoutHints, ay as getTwoColumnPositions, az as getViewport, aA as getViewportOrientation, aC as isTemplateBlock, aE as scaledFontSize } from '../Doc-BfBhiCNr.js';
 import { p as MarkdownHeading, l as MarkdownDocument } from '../types-DYAzisMG.js';
 import { C as ContentContainer } from '../ContentContainer-DNx460y8.js';
-export { D as DEFAULT_THEME, g as getAvailableThemes, b as getThemeSummaries, r as resolveTheme } from '../themeLibrary-DLJtGh8-.js';
+export { D as DEFAULT_THEME, g as getAvailableThemes, b as getThemeSummaries, r as resolveTheme } from '../themeLibrary-IP7EdyRq.js';
 
 /**
  * Persistent Layers Expansion
@@ -175,8 +175,8 @@ declare function mapBlock(input: MapBlockInput, context: TemplateContext): Layer
  * Input for coverBlock template - matches StartBlockConfig
  */
 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 */
@@ -579,6 +579,13 @@ interface MarkdownToDocOptions {
     defaultDuration?: number;
     /** 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;
 }
 /**
  * Convert a MarkdownDocument into a Doc with a heading-driven Block hierarchy.

package/dist/story/index.js

@@ -50,13 +50,13 @@ import {
   twoColumn,
   videoPullQuote,
   videoWithCaption
-} from "../chunk-T6WBC3ND.js";
+} from "../chunk-GAQLMORN.js";
 import {
   DEFAULT_THEME,
   getAvailableThemes,
   getThemeSummaries,
   resolveTheme
-} from "../chunk-TVPKD76V.js";
+} from "../chunk-53TZ2UTL.js";
 import {
   VIEWPORT_PRESETS,
   createTemplateContext,
@@ -67,7 +67,7 @@ import {
   isTemplateBlock,
   scaledFontSize2 as scaledFontSize
 } from "../chunk-QM5PKNPW.js";
-import "../chunk-QWVRN6I4.js";
+import "../chunk-7GF6RDED.js";
 import "../chunk-4X3JQXNM.js";
 import "../chunk-3E5F2XMR.js";
 export {

package/dist/{themeLibrary-DLJtGh8-.d.ts → themeLibrary-IP7EdyRq.d.ts}

@@ -1,4 +1,4 @@
-import { a7 as Theme } from './Doc-Dwn5aHFC.js';
+import { a7 as Theme } from './Doc-BfBhiCNr.js';
 
 /**
  * Built-in Theme Library

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bendyline/squisq",
-  "version": "1.2.0",
+  "version": "1.2.2",
   "description": "Headless utilities for doc/block rendering, spatial math, Markdown, and storage",
   "license": "MIT",
   "author": "Bendyline",
@@ -92,19 +92,19 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "hast-util-from-html": "^2.0.0",
-    "localforage": "^1.10.0",
-    "ngeohash": "^0.6.3",
-    "remark-directive": "^3.0.0",
-    "remark-frontmatter": "^5.0.0",
-    "remark-gfm": "^4.0.0",
-    "remark-math": "^6.0.0",
-    "remark-parse": "^11.0.0",
-    "remark-stringify": "^11.0.0",
-    "unified": "^11.0.0"
+    "hast-util-from-html": "2.0.3",
+    "localforage": "1.10.0",
+    "ngeohash": "0.6.3",
+    "remark-directive": "3.0.1",
+    "remark-frontmatter": "5.0.0",
+    "remark-gfm": "4.0.1",
+    "remark-math": "6.0.0",
+    "remark-parse": "11.0.0",
+    "remark-stringify": "11.0.0",
+    "unified": "11.0.5"
   },
   "devDependencies": {
-    "tsup": "^8.0.0",
-    "typescript": "^5.3.0"
+    "tsup": "8.5.1",
+    "typescript": "5.9.3"
   }
 }

package/src/__tests__/coverBlock.test.ts

@@ -0,0 +1,234 @@
+import { describe, it, expect } from 'vitest';
+import { coverBlock, expandCoverBlock, startBlockToCoverInput } from '../doc/templates/coverBlock';
+import { createTemplateContext, DEFAULT_THEME, VIEWPORT_PRESETS } from '../doc/templates/index';
+import type { StartBlockConfig } from '../schemas/Doc';
+import type { CoverBlockInput } from '../doc/templates/coverBlock';
+import type { ImageLayer, TextLayer, ShapeLayer } from '../schemas/Doc';
+
+// ── Helpers ──────────────────────────────────────────────────────────
+
+const landscapeContext = createTemplateContext(DEFAULT_THEME, 0, 1, VIEWPORT_PRESETS.landscape);
+const portraitContext = createTemplateContext(DEFAULT_THEME, 0, 1, VIEWPORT_PRESETS.portrait);
+
+function findLayer(layers: ReturnType<typeof coverBlock>, id: string) {
+  return layers.find((l) => l.id === id);
+}
+
+function findImage(layers: ReturnType<typeof coverBlock>, id: string) {
+  return findLayer(layers, id) as ImageLayer | undefined;
+}
+
+function findText(layers: ReturnType<typeof coverBlock>, id: string) {
+  return findLayer(layers, id) as TextLayer | undefined;
+}
+
+function findShape(layers: ReturnType<typeof coverBlock>, id: string) {
+  return findLayer(layers, id) as ShapeLayer | undefined;
+}
+
+// ── coverBlock with hero image ──────────────────────────────────────
+
+describe('coverBlock with hero image', () => {
+  const input: CoverBlockInput = {
+    heroSrc: 'hero.jpg',
+    heroAlt: 'Hero image',
+    title: 'Test Title',
+    subtitle: 'A subtitle',
+    ambientMotion: 'zoomIn',
+    heroCredit: 'Photographer',
+    heroLicense: 'CC-BY-4.0',
+  };
+
+  it('produces hero image layer', () => {
+    const layers = coverBlock(input, landscapeContext);
+    const hero = findImage(layers, 'cover-hero');
+    expect(hero).toBeDefined();
+    expect(hero!.type).toBe('image');
+    expect(hero!.content.src).toBe('hero.jpg');
+    expect(hero!.content.alt).toBe('Hero image');
+    expect(hero!.content.fit).toBe('cover');
+    expect(hero!.content.credit).toBe('Photographer');
+    expect(hero!.content.license).toBe('CC-BY-4.0');
+  });
+
+  it('produces gradient overlay', () => {
+    const layers = coverBlock(input, landscapeContext);
+    const gradient = findShape(layers, 'cover-gradient');
+    expect(gradient).toBeDefined();
+    expect(gradient!.type).toBe('shape');
+    expect(gradient!.content.fill).toContain('linear-gradient');
+  });
+
+  it('produces title layer with shadow', () => {
+    const layers = coverBlock(input, landscapeContext);
+    const title = findText(layers, 'cover-title');
+    expect(title).toBeDefined();
+    expect(title!.type).toBe('text');
+    expect(title!.content.text).toBe('Test Title');
+    expect(title!.content.style.shadow).toBe(true);
+    expect(title!.content.style.fontWeight).toBe('bold');
+  });
+
+  it('produces subtitle layer', () => {
+    const layers = coverBlock(input, landscapeContext);
+    const subtitle = findText(layers, 'cover-subtitle');
+    expect(subtitle).toBeDefined();
+    expect(subtitle!.type).toBe('text');
+    expect(subtitle!.content.text).toBe('A subtitle');
+  });
+
+  it('does not produce theme background layers', () => {
+    const layers = coverBlock(input, landscapeContext);
+    expect(findLayer(layers, 'cover-bg')).toBeUndefined();
+    expect(findLayer(layers, 'cover-accent')).toBeUndefined();
+  });
+
+  it('title positioned lower (over hero)', () => {
+    const layers = coverBlock(input, landscapeContext);
+    const title = findLayer(layers, 'cover-title');
+    // With subtitle: 70%, without: 75% — both below center
+    expect(title!.position.y).toBe('70%');
+  });
+
+  it('applies Ken Burns animation to hero image', () => {
+    const layers = coverBlock(input, landscapeContext);
+    const hero = findLayer(layers, 'cover-hero');
+    expect(hero!.animation).toBeDefined();
+  });
+});
+
+// ── coverBlock without hero image (theme background) ────────────────
+
+describe('coverBlock without hero image', () => {
+  const input: CoverBlockInput = {
+    title: 'Title Only',
+    subtitle: 'Subtitle text',
+  };
+
+  it('produces theme background instead of hero', () => {
+    const layers = coverBlock(input, landscapeContext);
+    const bg = findShape(layers, 'cover-bg');
+    expect(bg).toBeDefined();
+    expect(bg!.type).toBe('shape');
+    expect(bg!.content.fill).toContain('radial-gradient');
+  });
+
+  it('produces decorative accent line', () => {
+    const layers = coverBlock(input, landscapeContext);
+    const accent = findLayer(layers, 'cover-accent');
+    expect(accent).toBeDefined();
+    expect(accent!.type).toBe('shape');
+  });
+
+  it('does not produce hero image or gradient overlay', () => {
+    const layers = coverBlock(input, landscapeContext);
+    expect(findLayer(layers, 'cover-hero')).toBeUndefined();
+    expect(findLayer(layers, 'cover-gradient')).toBeUndefined();
+  });
+
+  it('title centered (not pushed to bottom)', () => {
+    const layers = coverBlock(input, landscapeContext);
+    const title = findLayer(layers, 'cover-title');
+    // Without hero: uses layout.primaryY which is typically around 35-40%
+    expect(title!.position.y).not.toBe('70%');
+    expect(title!.position.y).not.toBe('75%');
+  });
+
+  it('subtitle uses layout secondaryY', () => {
+    const layers = coverBlock(input, landscapeContext);
+    const subtitle = findLayer(layers, 'cover-subtitle');
+    expect(subtitle!.position.y).not.toBe('82%');
+  });
+});
+
+// ── coverBlock title-only (no subtitle) ─────────────────────────────
+
+describe('coverBlock title-only', () => {
+  it('no subtitle layer when subtitle is omitted', () => {
+    const layers = coverBlock({ title: 'Solo Title' }, landscapeContext);
+    expect(findLayer(layers, 'cover-subtitle')).toBeUndefined();
+  });
+
+  it('hero title at 75% when no subtitle', () => {
+    const layers = coverBlock({ heroSrc: 'img.jpg', title: 'Solo' }, landscapeContext);
+    const title = findLayer(layers, 'cover-title');
+    expect(title!.position.y).toBe('75%');
+  });
+
+  it('no-hero title at 50% when no subtitle', () => {
+    const layers = coverBlock({ title: 'Solo' }, landscapeContext);
+    const title = findLayer(layers, 'cover-title');
+    expect(title!.position.y).toBe('50%');
+  });
+});
+
+// ── Viewport scaling ────────────────────────────────────────────────
+
+describe('coverBlock viewport scaling', () => {
+  it('produces layers for portrait viewport', () => {
+    const layers = coverBlock({ heroSrc: 'img.jpg', title: 'Portrait' }, portraitContext);
+    expect(layers.length).toBeGreaterThanOrEqual(3); // hero + gradient + title
+  });
+
+  it('title font size differs between landscape and portrait', () => {
+    const landLayers = coverBlock({ title: 'Test' }, landscapeContext);
+    const portLayers = coverBlock({ title: 'Test' }, portraitContext);
+    const landTitle = findText(landLayers, 'cover-title');
+    const portTitle = findText(portLayers, 'cover-title');
+    expect(landTitle!.content.style.fontSize).not.toBe(portTitle!.content.style.fontSize);
+  });
+});
+
+// ── startBlockToCoverInput ──────────────────────────────────────────
+
+describe('startBlockToCoverInput', () => {
+  it('maps all StartBlockConfig fields to CoverBlockInput', () => {
+    const config: StartBlockConfig = {
+      heroSrc: 'hero.jpg',
+      heroAlt: 'Alt',
+      title: 'Title',
+      subtitle: 'Sub',
+      ambientMotion: 'panLeft',
+      heroCredit: 'Credit',
+      heroLicense: 'MIT',
+    };
+    const result = startBlockToCoverInput(config);
+    expect(result.heroSrc).toBe('hero.jpg');
+    expect(result.heroAlt).toBe('Alt');
+    expect(result.title).toBe('Title');
+    expect(result.subtitle).toBe('Sub');
+    expect(result.ambientMotion).toBe('panLeft');
+    expect(result.heroCredit).toBe('Credit');
+    expect(result.heroLicense).toBe('MIT');
+  });
+
+  it('handles config without heroSrc', () => {
+    const config: StartBlockConfig = { title: 'Title Only' };
+    const result = startBlockToCoverInput(config);
+    expect(result.heroSrc).toBeUndefined();
+    expect(result.title).toBe('Title Only');
+  });
+});
+
+// ── expandCoverBlock ────────────────────────────────────────────────
+
+describe('expandCoverBlock', () => {
+  it('returns layers from StartBlockConfig', () => {
+    const config: StartBlockConfig = {
+      heroSrc: 'cover.jpg',
+      title: 'Cover Title',
+    };
+    const layers = expandCoverBlock(config, landscapeContext);
+    expect(layers.length).toBeGreaterThanOrEqual(3);
+    expect(layers.some((l) => l.id === 'cover-hero')).toBe(true);
+    expect(layers.some((l) => l.id === 'cover-title')).toBe(true);
+  });
+
+  it('returns theme background layers when no heroSrc', () => {
+    const config: StartBlockConfig = { title: 'No Hero' };
+    const layers = expandCoverBlock(config, landscapeContext);
+    expect(layers.some((l) => l.id === 'cover-bg')).toBe(true);
+    expect(layers.some((l) => l.id === 'cover-title')).toBe(true);
+    expect(layers.some((l) => l.id === 'cover-hero')).toBe(false);
+  });
+});

package/src/__tests__/markdown.test.ts

@@ -591,6 +591,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/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;
+}