@bendyline/squisq 1.4.1 → 1.5.1

package/src/schemas/themes/tech-dark.json

@@ -14,9 +14,15 @@
     "warning": "#ff5252"
   },
   "typography": {
-    "bodyFont": { "stackId": "ibm-plex-sans" },
-    "titleFont": { "stackId": "jetbrains-mono" },
-    "monoFont": { "stackId": "jetbrains-mono" },
+    "bodyFont": {
+      "stackId": "ibm-plex-sans"
+    },
+    "titleFont": {
+      "stackId": "jetbrains-mono"
+    },
+    "monoFont": {
+      "stackId": "jetbrains-mono"
+    },
     "titleWeight": "bold",
     "titleScale": 0.9,
     "lineHeight": 1.5
@@ -25,24 +31,71 @@
     "textShadow": true,
     "overlayOpacity": 0.55,
     "animationSpeed": 0.9,
-    "borderRadius": 2
+    "borderRadius": 2,
+    "imageTreatment": {
+      "type": "cool",
+      "strength": 0.45
+    }
   },
   "renderStyle": {
     "name": "tech-dark",
     "defaultTextAnimation": "typewriter",
     "defaultImageAnimation": "slowZoom",
     "ambientMotion": true,
-    "defaultTransition": { "type": "dissolve", "duration": 0.4 },
+    "defaultTransition": {
+      "type": "dissolve",
+      "duration": 0.4
+    },
     "templateHints": {
-      "statHighlight": { "entrance": "dramatic" }
+      "statHighlight": {
+        "entrance": "dramatic"
+      }
     }
   },
   "colorSchemes": {
-    "blue": { "bg": "#0d1b2a", "text": "#00b0ff", "accent": "#40c4ff" },
-    "green": { "bg": "#0d1b0d", "text": "#00e676", "accent": "#69f0ae" },
-    "purple": { "bg": "#1a0d2e", "text": "#d500f9", "accent": "#ea80fc" },
-    "red": { "bg": "#2e0d0d", "text": "#ff5252", "accent": "#ff8a80" },
-    "orange": { "bg": "#2e1a0d", "text": "#ff9100", "accent": "#ffab40" },
-    "teal": { "bg": "#0d2e2e", "text": "#1de9b6", "accent": "#64ffda" }
+    "blue": {
+      "bg": "#0d1b2a",
+      "text": "#00b0ff",
+      "accent": "#40c4ff"
+    },
+    "green": {
+      "bg": "#0d1b0d",
+      "text": "#00e676",
+      "accent": "#69f0ae"
+    },
+    "purple": {
+      "bg": "#1a0d2e",
+      "text": "#d500f9",
+      "accent": "#ea80fc"
+    },
+    "red": {
+      "bg": "#2e0d0d",
+      "text": "#ff5252",
+      "accent": "#ff8a80"
+    },
+    "orange": {
+      "bg": "#2e1a0d",
+      "text": "#ff9100",
+      "accent": "#ffab40"
+    },
+    "teal": {
+      "bg": "#0d2e2e",
+      "text": "#1de9b6",
+      "accent": "#64ffda"
+    }
+  },
+  "persistentLayers": {
+    "topLayers": [
+      {
+        "template": "patternBackground",
+        "config": {
+          "type": "patternBackground",
+          "pattern": "grid",
+          "color": "#00e5ff",
+          "opacity": 0.04,
+          "scale": 1.5
+        }
+      }
+    ]
   }
 }

package/src/spatial/Geohash.ts

@@ -15,6 +15,7 @@
  */
 
 import ngeohash from 'ngeohash';
+import { haversineDistance } from './Haversine.js';
 
 /**
  * Encode latitude/longitude to a geohash string.
@@ -64,9 +65,7 @@ export function getNeighbors(hash: string): string[] {
  * // => ['c23n', 'c23p', 'c23q', 'c23j', 'c23m', 'c23k', 'c23h', 'c23e', 'c23s']
  */
 export function getGeohash4Neighbors(geohash4: string): string[] {
-  if (geohash4.length !== 4) {
-    throw new Error(`getGeohash4Neighbors requires 4-char geohash, got: ${geohash4}`);
-  }
+  if (geohash4.length !== 4) return [];
   const neighbors = getNeighbors(geohash4);
   return [geohash4, ...neighbors];
 }
@@ -92,18 +91,20 @@ export function getGeohashPrefix(geohash: string, precision: number): string {
  * performance issues.
  */
 export function geohashToHierarchicalPath(geohash4: string): string {
-  if (geohash4.length !== 4) {
-    throw new Error(`geohashToHierarchicalPath requires 4-char geohash, got: ${geohash4}`);
-  }
+  if (geohash4.length !== 4) return '';
   const [c1, c2, c3, c4] = geohash4.split('');
   return `${c1}/${c2}/${c3}/${c4}`;
 }
 
 /**
- * Compute all geohash cells along the path between two geohash cells.
- * Interpolates lat/lng points between the centers of `from` and `to`,
- * encoding each to a geohash at the given precision, and returns the
- * deduplicated list of intermediate cells (excluding `from` and `to`).
+ * Compute all geohash cells along the great-circle path between two geohash cells.
+ * Samples points along the spherical arc from `from` to `to`, encoding each to a
+ * geohash at the given precision, and returns the deduplicated list of intermediate
+ * cells (excluding `from` and `to`).
+ *
+ * Uses spherical linear interpolation (SLERP) via 3D unit vectors, which correctly
+ * handles antimeridian crossings and polar paths — both of which flat lat/lng
+ * interpolation gets wrong.
  */
 export function getGeohashPath(from: string, to: string, precision = 4): string[] {
   if (from === to) return [];
@@ -111,15 +112,34 @@ export function getGeohashPath(from: string, to: string, precision = 4): string[
   const fromCenter = decodeGeohash(from);
   const toCenter = decodeGeohash(to);
 
-  // Compute approximate distance to determine step count
-  const dLat = Math.abs(toCenter.lat - fromCenter.lat);
-  const dLng = Math.abs(toCenter.lng - fromCenter.lng);
-  // Rough km: 1 degree lat ≈ 111km, 1 degree lng ≈ 111km * cos(midLat)
-  const midLatRad = ((fromCenter.lat + toCenter.lat) / 2) * (Math.PI / 180);
-  const approxKm = Math.sqrt((dLat * 111) ** 2 + (dLng * 111 * Math.cos(midLatRad)) ** 2);
+  // Use haversine for accurate great-circle distance (step sizing)
+  const distKm = haversineDistance(
+    { lat: fromCenter.lat, lng: fromCenter.lng },
+    { lat: toCenter.lat, lng: toCenter.lng },
+  );
 
   // Step every ~15km to avoid skipping any geohash4 cell (~39x19km)
-  const steps = Math.max(2, Math.ceil(approxKm / 15));
+  const steps = Math.max(2, Math.ceil(distKm / 15));
+
+  // Convert endpoints to unit Cartesian vectors for SLERP
+  const φ1 = (fromCenter.lat * Math.PI) / 180;
+  const λ1 = (fromCenter.lng * Math.PI) / 180;
+  const φ2 = (toCenter.lat * Math.PI) / 180;
+  const λ2 = (toCenter.lng * Math.PI) / 180;
+
+  const x1 = Math.cos(φ1) * Math.cos(λ1);
+  const y1 = Math.cos(φ1) * Math.sin(λ1);
+  const z1 = Math.sin(φ1);
+  const x2 = Math.cos(φ2) * Math.cos(λ2);
+  const y2 = Math.cos(φ2) * Math.sin(λ2);
+  const z2 = Math.sin(φ2);
+
+  // Central angle between the two points
+  const dot = Math.max(-1, Math.min(1, x1 * x2 + y1 * y2 + z1 * z2));
+  const d = Math.acos(dot);
+  // Near-antipodal fallback: sin(d)≈0 means the great circle is undefined.
+  // Extremely unlikely for geohash path use; fall back to linear lat/lng.
+  const useLinear = Math.abs(Math.sin(d)) < 1e-10;
 
   const seen = new Set<string>();
   seen.add(from);
@@ -128,8 +148,20 @@ export function getGeohashPath(from: string, to: string, precision = 4): string[
   const path: string[] = [];
   for (let i = 1; i < steps; i++) {
     const t = i / steps;
-    const lat = fromCenter.lat + t * (toCenter.lat - fromCenter.lat);
-    const lng = fromCenter.lng + t * (toCenter.lng - fromCenter.lng);
+    let lat: number;
+    let lng: number;
+    if (useLinear) {
+      lat = fromCenter.lat + t * (toCenter.lat - fromCenter.lat);
+      lng = fromCenter.lng + t * (toCenter.lng - fromCenter.lng);
+    } else {
+      const A = Math.sin((1 - t) * d) / Math.sin(d);
+      const B = Math.sin(t * d) / Math.sin(d);
+      const x = A * x1 + B * x2;
+      const y = A * y1 + B * y2;
+      const z = A * z1 + B * z2;
+      lat = (Math.atan2(z, Math.sqrt(x * x + y * y)) * 180) / Math.PI;
+      lng = (Math.atan2(y, x) * 180) / Math.PI;
+    }
     const hash = encodeGeohash(lat, lng, precision);
     if (!seen.has(hash)) {
       seen.add(hash);
@@ -163,6 +195,5 @@ export function geohashOverlapsBounds(
   );
 }
 
-// haversineDistance is now in shared/spatial/Haversine.ts (canonical location).
 // Re-export for backwards compatibility with existing imports.
-export { haversineDistance } from './Haversine.js';
+export { haversineDistance };

package/src/storage/ContentContainer.ts

@@ -9,9 +9,9 @@
  * Paths are forward-slash separated strings relative to the container root
  * (e.g., 'images/hero.jpg', 'index.md'). No leading slash.
  *
- * Implementations:
+ * Implementations (in core):
  * - MemoryContentContainer — in-memory Map (for zip import, tests, transient use)
- * - SlotContentContainer — backed by IndexedDB slot storage (in the site package)
+ * - ScopedContentContainer — a prefix-scoped view onto a parent container
  */
 
 /**
@@ -44,6 +44,10 @@ export interface ContentContainer {
 
   /**
    * List files in the container.
+   *
+   * Returns file **entries** (`ContentEntry[]` with `.path`/`.mimeType`/`.size`),
+   * NOT bare path strings — despite the name. Read `entry.path` for the path;
+   * calling string methods (e.g. `.startsWith`) directly on an entry will throw.
    * @param prefix — Optional path prefix to filter by (e.g., 'images/')
    */
   listFiles(prefix?: string): Promise<ContentEntry[]>;

package/src/transform/applyTransform.ts

@@ -9,6 +9,7 @@
  */
 
 import type { Doc } from '../schemas/Doc.js';
+import type { DocBlock, TitleBlockInput, SectionHeaderInput } from '../schemas/BlockTemplates.js';
 import type { TransformStyleId, TransformOptions, TransformResult } from './types.js';
 import { resolveTransformStyle } from './registry.js';
 import { analyzeBlocks, extractDocImages } from './blockAnalyzer.js';
@@ -62,14 +63,43 @@ export function applyTransform(
   // 2. Select extractions and build template blocks
   const selection = selectAndBuild(analyzed, config, images, seed);
 
+  // 2b. Pacing bookends: an opening title beat and/or a closing beat.
+  let paced: DocBlock[] = selection.blocks;
+  let pacingInserted = 0;
+  const docTitle = firstTitle(doc);
+  if (config.pacing?.intro && docTitle && !doc.startBlock) {
+    const intro: TitleBlockInput = {
+      template: 'title',
+      id: 'transform-intro',
+      duration: 4,
+      audioSegment: 0,
+      title: docTitle,
+    };
+    paced = [intro, ...paced];
+    pacingInserted++;
+  }
+  if (config.pacing?.outro && docTitle) {
+    const outro: SectionHeaderInput = {
+      template: 'sectionHeader',
+      id: 'transform-outro',
+      duration: 3,
+      audioSegment: 0,
+      title: docTitle,
+      colorScheme: config.colorSchemes[0],
+    };
+    paced = [...paced, outro];
+    pacingInserted++;
+  }
+
   // 3. Allocate timing across the new block sequence
-  const timedBlocks = allocateTiming(selection.blocks, doc.duration);
+  const timedBlocks = allocateTiming(paced, doc.duration);
 
-  // 4. Assemble the output Doc
+  // 4. Assemble the output Doc. A style's suggested theme applies only
+  // when neither the caller nor the doc declares one.
   const transformedDoc: Doc = {
     ...doc,
     blocks: timedBlocks,
-    themeId: options?.themeId ?? doc.themeId,
+    themeId: options?.themeId ?? doc.themeId ?? config.suggestedThemeId,
   };
 
   return {
@@ -77,7 +107,16 @@ export function applyTransform(
     stats: {
       totalInputBlocks: doc.blocks.length,
       transformedBlocks: selection.transformedCount,
-      insertedBlocks: selection.insertedCount,
+      insertedBlocks: selection.insertedCount + pacingInserted,
     },
   };
 }
+
+/** First non-empty block title (the doc's working title). */
+function firstTitle(doc: Doc): string | undefined {
+  if (doc.startBlock?.title) return doc.startBlock.title;
+  for (const block of doc.blocks) {
+    if (block.title) return block.title;
+  }
+  return undefined;
+}

package/src/transform/index.ts

@@ -1,4 +1,5 @@
 export { applyTransform } from './applyTransform.js';
+export { registerTransformStyle, unregisterTransformStyle } from './registry.js';
 
 export {
   resolveTransformStyle,

package/src/transform/registry.ts

@@ -1,8 +1,10 @@
 /**
  * Transform Style Registry
  *
- * Central registry of built-in transform styles. Follows the same pattern
- * as themeLibrary.ts — a record of configs with lookup/summary helpers.
+ * Central registry of built-in transform styles plus a dynamic
+ * registration API. Follows the same pattern as themeLibrary.ts /
+ * `registerTheme` — registered styles take precedence over built-ins,
+ * unknown ids fall back to the default.
  */
 
 import type { TransformStyleConfig, TransformStyleSummary } from './types.js';
@@ -12,7 +14,7 @@ import { dataDrivenStyle } from './styles/dataDriven.js';
 import { narrativeStyle } from './styles/narrative.js';
 import { minimalStyle } from './styles/minimal.js';
 
-/** All registered transform styles, keyed by id. */
+/** All built-in transform styles, keyed by id. */
 const TRANSFORM_STYLES: Record<string, TransformStyleConfig> = {
   [documentaryStyle.id]: documentaryStyle,
   [magazineStyle.id]: magazineStyle,
@@ -21,27 +23,56 @@ const TRANSFORM_STYLES: Record<string, TransformStyleConfig> = {
   [minimalStyle.id]: minimalStyle,
 };
 
+/**
+ * Id aliases: the data-driven style's file/export are named `dataDriven`
+ * but its registered id is hyphenated — accept both.
+ */
+const STYLE_ALIASES: Record<string, string> = {
+  dataDriven: 'data-driven',
+};
+
+/** Host-registered custom styles (registered ids win over built-ins). */
+const registeredStyles = new Map<string, TransformStyleConfig>();
+
 /** Default style used when no id is provided. */
 export const DEFAULT_TRANSFORM_STYLE_ID = 'documentary';
 
 /**
- * Resolve a transform style by id.
- * Returns the default style if the id is not found.
+ * Register (or replace) a custom transform style at runtime. Hosts use
+ * this the same way they use `registerTheme` — to add product-specific
+ * styles without forking the registry.
+ */
+export function registerTransformStyle(style: TransformStyleConfig): void {
+  registeredStyles.set(style.id, style);
+}
+
+/** Remove a previously registered custom style. */
+export function unregisterTransformStyle(id: string): void {
+  registeredStyles.delete(id);
+}
+
+/**
+ * Resolve a transform style by id. Registered styles win over built-ins;
+ * aliases are honored; unknown ids fall back to the default style.
  */
 export function resolveTransformStyle(id: string): TransformStyleConfig {
-  return TRANSFORM_STYLES[id] ?? TRANSFORM_STYLES[DEFAULT_TRANSFORM_STYLE_ID];
+  const canonical = STYLE_ALIASES[id] ?? id;
+  return (
+    registeredStyles.get(canonical) ??
+    TRANSFORM_STYLES[canonical] ??
+    TRANSFORM_STYLES[DEFAULT_TRANSFORM_STYLE_ID]
+  );
 }
 
-/** Get all registered style ids. */
+/** Get all known style ids (built-ins plus registered). */
 export function getTransformStyleIds(): string[] {
-  return Object.keys(TRANSFORM_STYLES);
+  return Array.from(new Set([...Object.keys(TRANSFORM_STYLES), ...registeredStyles.keys()]));
 }
 
 /** Get summary info for all styles (for UI dropdowns). */
 export function getTransformStyleSummaries(): TransformStyleSummary[] {
-  return Object.values(TRANSFORM_STYLES).map(({ id, name, description }) => ({
-    id,
-    name,
-    description,
-  }));
+  return getTransformStyleIds().map((id) => {
+    const { name, description } = resolveTransformStyle(id);
+    return { id, name, description };
+  });
 }

package/src/transform/styles/dataDriven.ts

@@ -11,6 +11,7 @@ export const dataDrivenStyle: TransformStyleConfig = {
   colorSchemes: ['blue', 'orange', 'green', 'purple', 'red'],
   insertSectionHeaders: true,
   interleaveImages: false,
-  blocksPerSection: { min: 2, max: 6 },
+  blocksPerSection: { max: 6 },
   transitionStyle: 'cut',
+  suggestedThemeId: 'tech-dark',
 };

package/src/transform/styles/documentary.ts

@@ -11,6 +11,7 @@ export const documentaryStyle: TransformStyleConfig = {
   colorSchemes: ['blue', 'green', 'purple'],
   insertSectionHeaders: false,
   interleaveImages: true,
-  blocksPerSection: { min: 1, max: 3 },
+  blocksPerSection: { max: 3 },
   transitionStyle: 'fade',
+  suggestedThemeId: 'documentary',
 };

package/src/transform/styles/magazine.ts

@@ -11,6 +11,8 @@ export const magazineStyle: TransformStyleConfig = {
   colorSchemes: ['blue', 'green', 'purple', 'orange', 'red'],
   insertSectionHeaders: true,
   interleaveImages: true,
-  blocksPerSection: { min: 2, max: 5 },
+  blocksPerSection: { max: 5 },
   transitionStyle: 'dissolve',
+  suggestedThemeId: 'magazine',
+  templateMap: { quote: 'pullQuote', impactLine: 'fullBleedQuote' },
 };

package/src/transform/styles/minimal.ts

@@ -11,6 +11,7 @@ export const minimalStyle: TransformStyleConfig = {
   colorSchemes: ['blue', 'green'],
   insertSectionHeaders: false,
   interleaveImages: false,
-  blocksPerSection: { min: 1, max: 2 },
+  blocksPerSection: { max: 2 },
   transitionStyle: 'fade',
+  suggestedThemeId: 'minimalist',
 };

package/src/transform/styles/narrative.ts

@@ -11,6 +11,8 @@ export const narrativeStyle: TransformStyleConfig = {
   colorSchemes: ['blue', 'purple', 'green'],
   insertSectionHeaders: true,
   interleaveImages: true,
-  blocksPerSection: { min: 1, max: 4 },
+  blocksPerSection: { max: 4 },
   transitionStyle: 'fade',
+  suggestedThemeId: 'cinematic',
+  pacing: { intro: true, outro: true },
 };

package/src/transform/templateSelector.ts

@@ -6,13 +6,16 @@
  * variety. Ported and generalized from qualla-internal's TemplateSelector.
  */
 
-import type { Block } from '../schemas/Doc.js';
+import type { Block, TransitionType } from '../schemas/Doc.js';
 import type {
   TemplateBlock,
   AccentImage,
   AccentPosition,
   ImageWithCaptionInput,
   SectionHeaderInput,
+  QuoteBlockInput,
+  FullBleedQuoteInput,
+  StatHighlightInput,
 } from '../schemas/BlockTemplates.js';
 import type { ExtractedElement } from '../generate/contentExtractor.js';
 import type { TransformStyleConfig, TransformImage } from './types.js';
@@ -73,8 +76,17 @@ export function selectAndBuild(
   // 1. Collect all extractions across all blocks, filtered by config
   const candidates = collectCandidates(analyzed, config);
 
-  // 2. Determine how many blocks to transform
-  const maxTransforms = Math.max(1, Math.floor(analyzed.length * config.transformRatio));
+  // 2. Determine how many blocks to transform. `transformRatio` scales
+  // with block count; an optional duration-based budget (slides per
+  // minute) caps runaway promotion on long dense documents.
+  const ratioCap = Math.max(1, Math.floor(analyzed.length * config.transformRatio));
+  const slidesPerMinute = config.budget?.slidesPerMinute;
+  const totalDurationSeconds = analyzed.reduce((sum, ab) => sum + (ab.block.duration || 0), 0);
+  const budgetCap =
+    slidesPerMinute && totalDurationSeconds > 0
+      ? Math.max(1, Math.round((totalDurationSeconds / 60) * slidesPerMinute))
+      : Infinity;
+  const maxTransforms = Math.min(ratioCap, budgetCap);
   const selected = candidates.slice(0, maxTransforms);
 
   // 3. Build the output block sequence
@@ -233,7 +245,7 @@ function buildBlockSequence(
         accentPositionIndex++;
       }
 
-      const templateBlock = mapElementToBlock(sel.element, {
+      let templateBlock = mapElementToBlock(sel.element, {
         id: `transform-${blockIdCounter++}`,
         duration: ab.block.duration > 0 ? ab.block.duration / extractions.length : 6,
         audioSegment: ab.block.audioSegment,
@@ -242,15 +254,24 @@ function buildBlockSequence(
         sourceStartTime: sel.element.sourcePosition,
       });
 
+      // Style-level extraction→template remap (v2 contract). Only known
+      // text-compatible pairings translate; image-backed targets consume
+      // the accent image as their background. Unknown pairings keep the
+      // default mapping.
+      const remapTarget = config.templateMap?.[sel.element.data.type];
+      if (remapTarget && remapTarget !== templateBlock.template) {
+        const translated = translateTemplateBlock(templateBlock, remapTarget);
+        if (translated) templateBlock = translated;
+      }
+
       // Apply transition based on style
       if (config.transitionStyle !== 'cut') {
-        (
-          templateBlock as TemplateBlock & { transition?: { type: string; duration: number } }
-        ).transition = {
-          type:
-            config.transitionStyle === 'mixed'
-              ? (rng.pick(['fade', 'dissolve']) ?? 'fade')
-              : config.transitionStyle,
+        const transitionType: TransitionType =
+          config.transitionStyle === 'mixed'
+            ? (rng.pick<TransitionType>(['fade', 'dissolve']) ?? 'fade')
+            : config.transitionStyle;
+        templateBlock.transition = {
+          type: transitionType,
           duration: 0.5,
         };
       }
@@ -292,3 +313,58 @@ function buildBlockSequence(
 
   return { blocks, transformedCount, insertedCount };
 }
+
+/**
+ * Translate a mapped template block into a style-requested target
+ * template. Only text-compatible pairings are supported; returns null
+ * (keep the default) for unknown pairs or when a required input —
+ * a background image for `pullQuote` — is unavailable.
+ */
+function translateTemplateBlock(block: TemplateBlock, target: string): TemplateBlock | null {
+  const base = {
+    id: block.id,
+    duration: block.duration,
+    audioSegment: block.audioSegment,
+    sourceStartTime: block.sourceStartTime,
+    sourceDuration: block.sourceDuration,
+  };
+
+  if (block.template === 'quote') {
+    const quote = block as QuoteBlockInput;
+    if (target === 'fullBleedQuote') {
+      return { ...base, template: 'fullBleedQuote', text: quote.quote };
+    }
+    if (target === 'pullQuote') {
+      // pullQuote requires a full-bleed background image — reuse the
+      // accent image the selector already assigned to this block.
+      const bg = quote.accentImage;
+      if (!bg) return null;
+      return {
+        ...base,
+        template: 'pullQuote',
+        text: quote.quote,
+        attribution: quote.attribution,
+        backgroundImage: { src: bg.src, alt: bg.alt, credit: bg.credit, license: bg.license },
+      };
+    }
+    return null;
+  }
+
+  if (block.template === 'fullBleedQuote' && target === 'quote') {
+    const fbq = block as FullBleedQuoteInput;
+    return { ...base, template: 'quote', quote: fbq.text };
+  }
+
+  if (block.template === 'statHighlight' && target === 'factCard') {
+    const stat = block as StatHighlightInput;
+    return {
+      ...base,
+      template: 'factCard',
+      fact: stat.stat,
+      explanation: stat.description,
+      accentImage: stat.accentImage,
+    };
+  }
+
+  return null;
+}

package/src/transform/types.ts

@@ -57,11 +57,44 @@ export interface TransformStyleConfig {
   /** Whether to interleave imageWithCaption blocks when images are available. */
   interleaveImages: boolean;
 
-  /** Target density of template blocks per section. */
-  blocksPerSection: { min: number; max: number };
+  /** Maximum template blocks promoted per source section. */
+  blocksPerSection: { max: number };
 
   /** Transition style preference for transformed blocks. */
   transitionStyle: 'cut' | 'fade' | 'dissolve' | 'mixed';
+
+  /**
+   * Per-style extraction→template remapping. Falls back to the fixed
+   * default map in `generate/templateMapper.ts` for unmapped types.
+   * Only text-compatible targets are honored (see
+   * `translateTemplateBlock`) — an unknown pairing keeps the default.
+   */
+  templateMap?: Partial<Record<ExtractionType, string>>;
+
+  /**
+   * Theme this style pairs best with. Consumers (CLI, editor preview)
+   * apply it only when the doc doesn't already declare a `themeId`.
+   */
+  suggestedThemeId?: string;
+
+  /** Optional opening/closing beats added around the transformed doc. */
+  pacing?: {
+    /** Prepend a `title` block built from the doc's title. */
+    intro?: boolean;
+    /** Append a closing beat (best unused quote/impact line, else a sectionHeader). */
+    outro?: boolean;
+  };
+
+  /**
+   * Duration-based slide budget (folded in from the since-removed
+   * `generateSlideshow`): caps promoted template blocks at roughly
+   * `slidesPerMinute` of doc duration (default: uncapped — only
+   * `transformRatio` applies).
+   */
+  budget?: {
+    /** Target promoted blocks per minute of content (e.g. 5). */
+    slidesPerMinute?: number;
+  };
 }
 
 // ── Transform options ────────────────────────────────────────────