@bendyline/squisq 0.1.1 → 1.0.1

package/src/generate/index.ts

@@ -0,0 +1,21 @@
+export { extractContent, stripMarkdown } from './contentExtractor.js';
+export type {
+  ExtractionType,
+  ExtractedElement,
+  StatData,
+  DateData,
+  QuoteData,
+  ComparisonData,
+  FactData,
+  ImpactLineData,
+  ListData,
+  DefinitionData,
+  ExtractionOptions,
+  ExtractionResult,
+} from './contentExtractor.js';
+
+export { mapElementToBlock } from './templateMapper.js';
+export type { MapOptions } from './templateMapper.js';
+
+export { generateSlideshow } from './slideshowGenerator.js';
+export type { SlideshowDoc, SlideshowImage, SlideshowOptions } from './slideshowGenerator.js';

package/src/generate/slideshowGenerator.ts

@@ -0,0 +1,273 @@
+/**
+ * Slideshow Generator
+ *
+ * Turns plain text + optional images into a complete squisq `Doc`.
+ *
+ * Pipeline:
+ * 1. Strip markdown (if needed)
+ * 2. Extract compelling content (stats, dates, quotes, …)
+ * 3. Estimate narration timing
+ * 4. Map extractions → template blocks
+ * 5. Interleave image slides
+ * 6. Return a ready-to-render `Doc`
+ */
+
+import type { Doc } from '../schemas/Doc.js';
+import type {
+  TemplateBlock,
+  ImageWithCaptionInput,
+  TitleBlockInput,
+  ColorScheme,
+  AccentImage,
+  AccentPosition,
+} from '../schemas/BlockTemplates.js';
+import { extractContent, stripMarkdown } from './contentExtractor.js';
+import { mapElementToBlock } from './templateMapper.js';
+import { estimateNarrationDuration } from '../timing/narrationTiming.js';
+import { SeededRandom, hashString } from '../random/SeededRandom.js';
+
+// ── Public types ───────────────────────────────────────────────────
+
+/** A Doc variant whose blocks are TemplateBlocks (no startTime required). */
+export type SlideshowDoc = Omit<Doc, 'blocks'> & {
+  blocks: TemplateBlock[];
+};
+
+/** Image metadata passed to the generator. */
+export interface SlideshowImage {
+  /** Image source path or URL. */
+  src: string;
+  /** Alt text for accessibility. */
+  alt?: string;
+  /** Photo credit. */
+  credit?: string;
+  /** License identifier. */
+  license?: string;
+}
+
+/** Options for `generateSlideshow`. */
+export interface SlideshowOptions {
+  /** Deterministic seed (default: hash of the text). */
+  seed?: number;
+  /** Title slide text. Omit to skip the title slide. */
+  title?: string;
+  /** Subtitle for the title slide. */
+  subtitle?: string;
+  /** Explicit total duration in seconds. When omitted, estimated from text. */
+  duration?: number;
+  /** Target number of content slides (default: 5–8, auto-scaled). */
+  targetSlides?: number;
+  /** Color schemes to rotate (default: ['blue','green','purple','orange','red']). */
+  colorSchemes?: ColorScheme[];
+  /** Ambient motions to rotate on images. */
+  ambientMotions?: Array<'zoomIn' | 'zoomOut' | 'panLeft' | 'panRight'>;
+  /** Accent positions to rotate on text slides. */
+  accentPositions?: AccentPosition[];
+  /** Minimum slide duration in seconds (default: 4). */
+  minSlideDuration?: number;
+  /** Maximum slide duration in seconds (default: 15). */
+  maxSlideDuration?: number;
+  /** Theme identifier to embed in the Doc. */
+  themeId?: string;
+  /** Whether the input text is markdown (default: false). */
+  isMarkdown?: boolean;
+  /** Minimum extraction confidence (default: 0.3). */
+  minConfidence?: number;
+}
+
+const DEFAULT_COLOR_SCHEMES: ColorScheme[] = ['blue', 'green', 'purple', 'orange', 'red'];
+const DEFAULT_AMBIENT_MOTIONS: Array<'zoomIn' | 'zoomOut' | 'panLeft' | 'panRight'> = [
+  'zoomIn',
+  'zoomOut',
+  'panLeft',
+  'panRight',
+];
+const DEFAULT_ACCENT_POSITIONS: AccentPosition[] = ['left-strip', 'right-strip', 'bottom-strip'];
+
+// ── Main ───────────────────────────────────────────────────────────
+
+/**
+ * Generate a slideshow `Doc` from text and optional images.
+ *
+ * ```ts
+ * const doc = generateSlideshow(articleText, myImages, {
+ *   title: 'Mount Rainier',
+ *   themeId: 'documentary',
+ * });
+ * // doc is a complete Doc ready for DocPlayer / LinearDocView
+ * ```
+ */
+export function generateSlideshow(
+  text: string,
+  images: SlideshowImage[] = [],
+  options: SlideshowOptions = {},
+): SlideshowDoc {
+  const {
+    seed,
+    title,
+    subtitle,
+    duration: explicitDuration,
+    targetSlides,
+    colorSchemes = DEFAULT_COLOR_SCHEMES,
+    ambientMotions = DEFAULT_AMBIENT_MOTIONS,
+    accentPositions = DEFAULT_ACCENT_POSITIONS,
+    minSlideDuration = 4,
+    maxSlideDuration = 15,
+    themeId,
+    isMarkdown = false,
+    minConfidence = 0.3,
+  } = options;
+
+  const plainText = isMarkdown ? stripMarkdown(text) : text;
+  const rng = new SeededRandom(seed ?? hashString(plainText));
+
+  // 1. Estimate total duration
+  const totalDuration = explicitDuration ?? estimateNarrationDuration(plainText);
+
+  // 2. Extract compelling content
+  const extraction = extractContent(plainText, { minConfidence });
+  const allElements = extraction.elements;
+
+  // 3. Decide slide budget
+  const slideBudget = targetSlides ?? computeSlideBudget(totalDuration, allElements.length);
+
+  // Allocate slots between content and images
+  const imageSlotCount = images.length > 0 ? Math.max(1, Math.round(slideBudget * 0.4)) : 0;
+  const contentSlotCount = Math.max(0, slideBudget - imageSlotCount - (title ? 1 : 0));
+
+  // Select top elements by confidence, then restore source order
+  const sorted = [...allElements].sort((a, b) => b.confidence - a.confidence);
+  const selected = sorted.slice(0, contentSlotCount);
+  selected.sort((a, b) => a.sourcePosition - b.sourcePosition);
+
+  // 4. Build slides
+  const blocks: TemplateBlock[] = [];
+  let slideIndex = 0;
+  let colorIdx = 0;
+  let accentIdx = 0;
+
+  // Determine per-slide duration
+  const totalSlideCount =
+    (title ? 1 : 0) + selected.length + Math.min(imageSlotCount, images.length);
+  const perSlide =
+    totalSlideCount > 0
+      ? Math.min(maxSlideDuration, Math.max(minSlideDuration, totalDuration / totalSlideCount))
+      : minSlideDuration;
+
+  // Title slide
+  if (title) {
+    const titleBlock: TitleBlockInput = {
+      id: `slide-${slideIndex++}`,
+      template: 'titleBlock',
+      title,
+      subtitle,
+      duration: Math.min(perSlide, 6),
+      audioSegment: 0,
+    };
+    blocks.push(titleBlock);
+  }
+
+  // Prepare image pool for standalone + accent images
+  const standaloneImages = images.slice(0, Math.min(imageSlotCount, images.length));
+  const accentPool =
+    images.length > standaloneImages.length ? images.slice(standaloneImages.length) : [...images]; // reuse if not enough
+
+  // Interleave pattern: insert an image slide every N content slides
+  const imageInterval =
+    standaloneImages.length > 0
+      ? Math.max(1, Math.floor(selected.length / (standaloneImages.length + 1)))
+      : Infinity;
+  let imgIdx = 0;
+  let sinceImage = 0;
+
+  for (let i = 0; i < selected.length; i++) {
+    // Maybe insert a standalone image slide before this content slide
+    if (sinceImage >= imageInterval && imgIdx < standaloneImages.length) {
+      blocks.push(
+        createImageSlide(standaloneImages[imgIdx], slideIndex++, perSlide, rng, ambientMotions),
+      );
+      imgIdx++;
+      sinceImage = 0;
+    }
+
+    const element = selected[i];
+
+    // Optional accent image
+    let accentImage: AccentImage | undefined;
+    if (accentPool.length > 0) {
+      const img = accentPool[i % accentPool.length];
+      accentImage = {
+        src: img.src,
+        alt: img.alt ?? '',
+        position: accentPositions[accentIdx % accentPositions.length],
+        ambientMotion: rng.pickRequired(ambientMotions),
+        credit: img.credit,
+        license: img.license,
+      };
+      accentIdx++;
+    }
+
+    const block = mapElementToBlock(element, {
+      id: `slide-${slideIndex++}`,
+      duration: perSlide,
+      audioSegment: 0,
+      colorScheme: colorSchemes[colorIdx % colorSchemes.length],
+      accentImage,
+    });
+    blocks.push(block);
+    colorIdx++;
+    sinceImage++;
+  }
+
+  // Append any remaining standalone images
+  while (imgIdx < standaloneImages.length) {
+    blocks.push(
+      createImageSlide(standaloneImages[imgIdx], slideIndex++, perSlide, rng, ambientMotions),
+    );
+    imgIdx++;
+  }
+
+  // 5. Assemble Doc
+  const doc: SlideshowDoc = {
+    articleId: title ?? 'slideshow',
+    duration: totalDuration,
+    blocks,
+    audio: {
+      segments: [{ src: '', name: 'main', duration: totalDuration, startTime: 0 }],
+    },
+    themeId,
+  };
+
+  return doc;
+}
+
+// ── Helpers ────────────────────────────────────────────────────────
+
+function computeSlideBudget(duration: number, elementCount: number): number {
+  // Aim for ~5 slides per minute of content, clamped 3–12
+  const byDuration = Math.round((duration / 60) * 5);
+  // But don't exceed available elements + a few image slots
+  const budget = Math.min(byDuration, elementCount + 4);
+  return Math.max(3, Math.min(12, budget));
+}
+
+function createImageSlide(
+  img: SlideshowImage,
+  index: number,
+  duration: number,
+  rng: SeededRandom,
+  motions: Array<'zoomIn' | 'zoomOut' | 'panLeft' | 'panRight'>,
+): ImageWithCaptionInput {
+  return {
+    id: `slide-${index}`,
+    template: 'imageWithCaption',
+    imageSrc: img.src,
+    imageAlt: img.alt ?? '',
+    caption: img.alt,
+    duration,
+    audioSegment: 0,
+    ambientMotion: rng.pickRequired(motions),
+    imageCredit: img.credit,
+    imageLicense: img.license,
+  };
+}

package/src/generate/templateMapper.ts

@@ -0,0 +1,170 @@
+/**
+ * Template Mapper
+ *
+ * Converts extracted content elements into squisq TemplateBlock inputs.
+ * Each ExtractionType maps to a specific template from BlockTemplates.
+ */
+
+import type {
+  ExtractedElement,
+  StatData,
+  DateData,
+  QuoteData,
+  ComparisonData,
+  FactData,
+  ImpactLineData,
+  ListData,
+  DefinitionData,
+} from './contentExtractor.js';
+
+import type {
+  StatHighlightInput,
+  QuoteBlockInput,
+  FactCardInput,
+  TwoColumnInput,
+  DateEventInput,
+  FullBleedQuoteInput,
+  ListBlockInput,
+  DefinitionCardInput,
+  TemplateBlock,
+  ColorScheme,
+  AccentImage,
+} from '../schemas/BlockTemplates.js';
+
+/** Options for mapping an element to a template block. */
+export interface MapOptions {
+  id: string;
+  duration: number;
+  audioSegment: number;
+  colorScheme?: ColorScheme;
+  accentImage?: AccentImage;
+  sourceStartTime?: number;
+  sourceDuration?: number;
+}
+
+/**
+ * Convert an extracted element into the matching squisq TemplateBlock.
+ */
+export function mapElementToBlock(element: ExtractedElement, options: MapOptions): TemplateBlock {
+  const base = {
+    id: options.id,
+    duration: options.duration,
+    audioSegment: options.audioSegment,
+    sourceStartTime: options.sourceStartTime,
+    sourceDuration: options.sourceDuration,
+  };
+
+  switch (element.data.type) {
+    case 'stat':
+      return mapStat(element.data, base, options);
+    case 'date':
+      return mapDate(element.data, base, options);
+    case 'quote':
+      return mapQuote(element.data, base, options);
+    case 'comparison':
+      return mapComparison(element.data, base, options);
+    case 'fact':
+      return mapFact(element.data, base, options);
+    case 'impactLine':
+      return mapImpactLine(element.data, base, options);
+    case 'list':
+      return mapList(element.data, base, options);
+    case 'definition':
+      return mapDefinition(element.data, base, options);
+  }
+}
+
+// ── Per-type mappers ───────────────────────────────────────────────
+
+type Base = {
+  id: string;
+  duration: number;
+  audioSegment: number;
+  sourceStartTime?: number;
+  sourceDuration?: number;
+};
+
+function mapStat(data: StatData, base: Base, opts: MapOptions): StatHighlightInput {
+  return {
+    ...base,
+    template: 'statHighlight',
+    stat: data.value,
+    description: data.description,
+    colorScheme: opts.colorScheme,
+    accentImage: opts.accentImage,
+  };
+}
+
+function mapDate(data: DateData, base: Base, opts: MapOptions): DateEventInput {
+  return {
+    ...base,
+    template: 'dateEvent',
+    date: data.date,
+    description: data.description,
+    mood: data.mood,
+    accentImage: opts.accentImage,
+  };
+}
+
+function mapQuote(data: QuoteData, base: Base, opts: MapOptions): QuoteBlockInput {
+  return {
+    ...base,
+    template: 'quoteBlock',
+    quote: data.quote,
+    attribution: data.attribution,
+    accentImage: opts.accentImage,
+  };
+}
+
+function mapComparison(data: ComparisonData, base: Base, opts: MapOptions): TwoColumnInput {
+  return {
+    ...base,
+    template: 'twoColumn',
+    left: data.left,
+    right: data.right,
+    header: data.header,
+    leftColor: opts.colorScheme,
+  };
+}
+
+function mapFact(data: FactData, base: Base, opts: MapOptions): FactCardInput {
+  return {
+    ...base,
+    template: 'factCard',
+    fact: data.fact,
+    explanation: data.explanation ?? '',
+    accentImage: opts.accentImage,
+  };
+}
+
+function mapImpactLine(data: ImpactLineData, base: Base, opts: MapOptions): FullBleedQuoteInput {
+  return {
+    ...base,
+    template: 'fullBleedQuote',
+    text: data.text,
+    colorScheme: opts.colorScheme,
+  };
+}
+
+function mapList(data: ListData, base: Base, opts: MapOptions): ListBlockInput {
+  return {
+    ...base,
+    template: 'listBlock',
+    items: data.items,
+    title: data.title,
+    colorScheme: opts.colorScheme,
+    accentImage: opts.accentImage,
+  };
+}
+
+function mapDefinition(data: DefinitionData, base: Base, opts: MapOptions): DefinitionCardInput {
+  return {
+    ...base,
+    template: 'definitionCard',
+    term: data.term,
+    definition: data.definition,
+    origin: data.origin,
+    colorScheme: opts.colorScheme,
+    accentImage: opts.accentImage,
+  };
+}

package/src/index.ts

@@ -3,3 +3,6 @@ export * from './doc/index.js';
 export * from './spatial/index.js';
 export * from './storage/index.js';
 export * from './markdown/index.js';
+export * from './timing/index.js';
+export * from './random/index.js';
+export * from './generate/index.js';

package/src/random/SeededRandom.ts

@@ -0,0 +1,127 @@
+/**
+ * Seeded pseudo-random number generator (Mulberry32 algorithm).
+ *
+ * Provides deterministic, reproducible randomness from an integer seed.
+ * Useful for consistent slideshow generation, shuffling, and selection.
+ *
+ * ```ts
+ * const rng = new SeededRandom(42);
+ * rng.next();            // 0.0–1.0
+ * rng.nextInt(10);       // 0–9
+ * rng.pick(['a', 'b']);  // 'a' or 'b'
+ * ```
+ */
+export class SeededRandom {
+  private state: number;
+
+  constructor(seed: number) {
+    this.state = seed >>> 0;
+    if (this.state === 0) {
+      this.state = 0xdeadbeef;
+    }
+  }
+
+  /** Random float in [0, 1). */
+  next(): number {
+    let t = (this.state += 0x6d2b79f5);
+    t = Math.imul(t ^ (t >>> 15), t | 1);
+    t ^= t + Math.imul(t ^ (t >>> 7), t | 61);
+    return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
+  }
+
+  /** Random integer in [0, max). */
+  nextInt(max: number): number {
+    return Math.floor(this.next() * max);
+  }
+
+  /** Random integer in [min, max). */
+  nextIntRange(min: number, max: number): number {
+    return min + Math.floor(this.next() * (max - min));
+  }
+
+  /** Random boolean with given probability of `true` (default 0.5). */
+  nextBool(probability: number = 0.5): boolean {
+    return this.next() < probability;
+  }
+
+  /** Pick a random element, or `undefined` if array is empty. */
+  pick<T>(array: T[]): T | undefined {
+    if (array.length === 0) return undefined;
+    return array[this.nextInt(array.length)];
+  }
+
+  /** Pick a random element; throws if empty. */
+  pickRequired<T>(array: T[]): T {
+    if (array.length === 0) {
+      throw new Error('Cannot pick from empty array');
+    }
+    return array[this.nextInt(array.length)];
+  }
+
+  /** Pick `count` unique random elements (fewer if array is smaller). */
+  pickMultiple<T>(array: T[], count: number): T[] {
+    if (count >= array.length) {
+      return this.shuffle([...array]);
+    }
+    const result: T[] = [];
+    const available = [...array];
+    for (let i = 0; i < count && available.length > 0; i++) {
+      const index = this.nextInt(available.length);
+      result.push(available[index]);
+      available.splice(index, 1);
+    }
+    return result;
+  }
+
+  /** Fisher-Yates shuffle **in place**. Returns the same array. */
+  shuffle<T>(array: T[]): T[] {
+    for (let i = array.length - 1; i > 0; i--) {
+      const j = this.nextInt(i + 1);
+      [array[i], array[j]] = [array[j], array[i]];
+    }
+    return array;
+  }
+
+  /** Return a **new** shuffled copy. */
+  shuffled<T>(array: readonly T[]): T[] {
+    return this.shuffle([...array]);
+  }
+
+  /** Weighted random selection. Returns `undefined` if items is empty. */
+  pickWeighted<T>(items: { item: T; weight: number }[]): T | undefined {
+    if (items.length === 0) return undefined;
+
+    const totalWeight = items.reduce((sum, { weight }) => sum + weight, 0);
+    if (totalWeight <= 0) return items[0]?.item;
+
+    let random = this.next() * totalWeight;
+    for (const { item, weight } of items) {
+      random -= weight;
+      if (random <= 0) return item;
+    }
+    return items[items.length - 1]?.item;
+  }
+
+  /** Current internal state (for debugging / serialization). */
+  getState(): number {
+    return this.state;
+  }
+
+  /** Create an independent sub-stream keyed by a modifier. */
+  derive(modifier: string | number): SeededRandom {
+    const hash = typeof modifier === 'string' ? hashString(modifier) : modifier >>> 0;
+    return new SeededRandom(this.state ^ hash);
+  }
+}
+
+/**
+ * Simple string → 32-bit hash (djb2 algorithm).
+ * Useful for turning a document ID into a numeric seed.
+ */
+export function hashString(str: string): number {
+  let hash = 5381;
+  for (let i = 0; i < str.length; i++) {
+    hash = ((hash << 5) + hash) ^ str.charCodeAt(i);
+  }
+  return hash >>> 0;
+}

package/src/random/index.ts

@@ -0,0 +1 @@
+export { SeededRandom, hashString } from './SeededRandom.js';

package/src/timing/index.ts

@@ -0,0 +1,17 @@
+export {
+  DEFAULT_WORDS_PER_SECOND,
+  estimateSpokenWordCount,
+  countSpokenWords,
+  estimateTimeFromText,
+  calculatePrefixDuration,
+  estimateNarrationDuration,
+} from './narrationTiming.js';
+
+export { estimateReadingTime, estimateNarrationTime } from './readingTime.js';
+
+export type {
+  ReadingTimeEstimate,
+  ReadingTimeOptions,
+  NarrationTimeEstimate,
+  NarrationTimeOptions,
+} from './readingTime.js';