@bendyline/squisq 0.1.1 → 1.0.1

package/dist/schemas/Doc.d.ts

@@ -0,0 +1,411 @@
+/**
+ * Doc Schema
+ *
+ * Defines the JSON format for AI-scriptable visual docs that accompany
+ * audio narration. A Doc describes a sequence of animated blocks
+ * with text overlays, images, and transitions synchronized to audio.
+ *
+ * The format is designed to be:
+ * 1. AI-generatable - Claude can create scripts from article content
+ * 2. Browser-renderable - SVG + CSS animations (ES2015 compatible)
+ * 3. Video-exportable - Frame-by-frame capture via Playwright
+ *
+ * Timing: Blocks are timed to match narration audio segments. Each article
+ * has 3-6 MP3 files (intro + sections), and blocks are grouped by segment.
+ */
+/**
+ * Configuration for the Start/resting block shown before playback begins.
+ */
+export interface StartBlockConfig {
+    /** Hero image path (relative to article media) */
+    heroSrc: string;
+    /** Alt text for the hero image */
+    heroAlt?: string;
+    /** Title to display over the hero */
+    title: string;
+    /** Optional subtitle */
+    subtitle?: string;
+    /** Ambient motion for the hero image */
+    ambientMotion?: 'zoomIn' | 'zoomOut' | 'panLeft' | 'panRight';
+    /** Photo credit / artist name for the hero image */
+    heroCredit?: string;
+    /** License identifier for the hero image */
+    heroLicense?: string;
+}
+/**
+ * A complete visual doc for an article.
+ */
+export interface Doc {
+    /** Article ID this doc belongs to */
+    articleId: string;
+    /** Total duration in seconds (sum of all audio segments) */
+    duration: number;
+    /** Ordered list of blocks */
+    blocks: Block[];
+    /** Audio track configuration */
+    audio: AudioTrack;
+    /** Caption track for closed captions (generated by postprocess-doc) */
+    captions?: CaptionTrack;
+    /**
+     * Start/resting block shown before playback begins.
+     * Displays hero image with title - acts as a "poster" for the doc.
+     * The player shows this until the user starts playback.
+     */
+    startBlock?: StartBlockConfig;
+    /**
+     * Persistent layers rendered on every block (behind and/or on top of content).
+     * Used for consistent branding overlays, background gradients, etc.
+     */
+    persistentLayers?: import('./BlockTemplates.js').PersistentLayerConfig;
+    /**
+     * Optional theme identifier. Resolved at render time via `resolveTheme()`.
+     * When omitted, the renderer uses the default theme ('documentary').
+     */
+    themeId?: string;
+    /** Optional metadata */
+    meta?: {
+        generatedAt?: string;
+        generatedBy?: string;
+        version?: number;
+    };
+    /**
+     * YAML frontmatter from the source markdown.
+     * Carries rendering hints like `document-render-as` and custom metadata.
+     */
+    frontmatter?: Record<string, unknown>;
+}
+/**
+ * A single block in the doc.
+ *
+ * Blocks can be flat (audio-synced timeline) or nested (markdown-driven hierarchy).
+ * When derived from markdown, a block corresponds to a heading section:
+ * - `sourceHeading` references the original MarkdownHeading node
+ * - `contents` holds the body markdown between this heading and the next
+ * - `children` holds sub-heading blocks (e.g., H2s under an H1)
+ */
+export interface Block {
+    /** Unique identifier for this block */
+    id: string;
+    /** When this block appears (seconds from start) */
+    startTime: number;
+    /** How long this block is visible (seconds) */
+    duration: number;
+    /** Which audio segment this block belongs to (0-indexed) */
+    audioSegment: number;
+    /**
+     * Pre-computed visual layers, rendered back-to-front.
+     *
+     * Optional — template-derived blocks typically omit this and compute
+     * layers on demand via `getLayers()` from `@bendyline/squisq/doc`.
+     * Raw blocks (e.g., hand-crafted by AI) may provide layers directly.
+     */
+    layers?: Layer[];
+    /** Entry transition from previous block */
+    transition?: Transition;
+    /** Template name that generated this block (for debugging) */
+    template?: string;
+    /**
+     * Nested sub-blocks (heading hierarchy).
+     * When a doc is derived from markdown, sub-headings within this
+     * heading's section become child blocks. For example, H2 blocks
+     * under an H1 block appear here.
+     */
+    children?: Block[];
+    /**
+     * Markdown body content for this block's section.
+     * Contains the block-level markdown nodes (paragraphs, lists, code,
+     * blockquotes, etc.) that appear between this heading and the next
+     * heading or sub-heading. Empty for pure structural blocks.
+     */
+    contents?: import('../markdown/types.js').MarkdownBlockNode[];
+    /**
+     * Reference to the MarkdownHeading node that created this block.
+     * Present when the block was derived from markdown via markdownToDoc().
+     * Enables round-tripping back to markdown and provides heading depth.
+     * Absent for the preamble block (content before the first heading).
+     */
+    sourceHeading?: import('../markdown/types.js').MarkdownHeading;
+    /**
+     * Template overrides extracted from markdown directives.
+     * For example, `### Data Section {template=chart colorScheme=blue}`
+     * would produce `{ template: 'chart', colorScheme: 'blue' }`.
+     * Allows per-block customization of template selection and parameters.
+     */
+    templateOverrides?: Record<string, string>;
+}
+/**
+ * A visual element within a block.
+ * Layers are composited back-to-front (first layer is background).
+ */
+export type Layer = ImageLayer | TextLayer | ShapeLayer | MapLayer | VideoLayer;
+interface BaseLayer {
+    /** Unique identifier for this layer */
+    id: string;
+    /** Position and size */
+    position: Position;
+    /** Animation to apply */
+    animation?: Animation;
+}
+/**
+ * Image layer - displays an image with optional Ken Burns effect.
+ */
+export interface ImageLayer extends BaseLayer {
+    type: 'image';
+    content: {
+        /** Path to image file (relative to article media dir) */
+        src: string;
+        /** Alt text for accessibility */
+        alt: string;
+        /** How to fit image in bounds */
+        fit?: 'cover' | 'contain' | 'fill';
+        /** Photo credit / artist name */
+        credit?: string;
+        /** License identifier (e.g., 'CC BY-SA 4.0') */
+        license?: string;
+    };
+}
+/**
+ * Text layer - displays text with styling.
+ */
+export interface TextLayer extends BaseLayer {
+    type: 'text';
+    content: {
+        /** Text to display (supports \n for line breaks) */
+        text: string;
+        /** Text styling */
+        style: TextStyle;
+    };
+}
+/**
+ * Shape layer - simple geometric shapes for visual accents.
+ */
+export interface ShapeLayer extends BaseLayer {
+    type: 'shape';
+    content: {
+        /** Shape type */
+        shape: 'rect' | 'circle' | 'line';
+        /** Fill color (CSS color or 'none') */
+        fill?: string;
+        /** Stroke color */
+        stroke?: string;
+        /** Stroke width in pixels */
+        strokeWidth?: number;
+        /** Corner radius for rect */
+        borderRadius?: number;
+    };
+}
+/**
+ * Map layer - displays a geographic map with optional markers.
+ *
+ * Maps are rendered as composite tile images from free tile providers.
+ * Supported styles use open-source/free tiles requiring attribution.
+ */
+export interface MapLayer extends BaseLayer {
+    type: 'map';
+    content: {
+        /** Center coordinates for the map */
+        center: {
+            lat: number;
+            lng: number;
+        };
+        /** Zoom level (0-18, typically 8-14 for doc blocks) */
+        zoom: number;
+        /** Map tile style */
+        style: MapTileStyle;
+        /** Optional markers to display on the map */
+        markers?: MapMarker[];
+        /** Pre-rendered static image path (for video export reliability) */
+        staticSrc?: string;
+        /** Show attribution text (default: true) */
+        showAttribution?: boolean;
+    };
+}
+/**
+ * Video layer - displays a short video clip, always muted (narration provides audio).
+ *
+ * Rendered via an HTML5 <video> element inside <foreignObject>, similar to how
+ * ImageLayer uses <img> for Ken Burns effects. clipStart/clipEnd define the window
+ * within the source video to play. During Playwright frame capture (seekTo mode),
+ * the video is seeked programmatically rather than playing in real time.
+ */
+export interface VideoLayer extends BaseLayer {
+    type: 'video';
+    content: {
+        /** Path to video file (relative to article media dir) */
+        src: string;
+        /** Path to poster frame (shown before video loads / during seek) */
+        posterSrc?: string;
+        /** Alt text for accessibility */
+        alt: string;
+        /** How to fit video in bounds */
+        fit?: 'cover' | 'contain' | 'fill';
+        /** Start time within the source video (seconds) */
+        clipStart: number;
+        /** End time within the source video (seconds) */
+        clipEnd: number;
+        /** Total source video duration (for validation) */
+        sourceDuration?: number;
+        /** Video credit / artist name */
+        credit?: string;
+        /** License identifier (e.g., 'CC BY-SA 4.0') */
+        license?: string;
+    };
+}
+/**
+ * Available map tile styles from free/open-source providers.
+ */
+export type MapTileStyle = 'terrain' | 'satellite' | 'road' | 'toner' | 'watercolor';
+/**
+ * A marker to display on the map.
+ */
+export interface MapMarker {
+    /** Marker latitude */
+    lat: number;
+    /** Marker longitude */
+    lng: number;
+    /** Optional label text */
+    label?: string;
+    /** Marker color (CSS color, default: #ef4444) */
+    color?: string;
+    /** Marker icon type */
+    icon?: 'pin' | 'circle' | 'star';
+}
+/**
+ * Position and dimensions for a layer.
+ * Values can be pixels (number) or percentages (string like "50%").
+ */
+export interface Position {
+    /** X position (pixels or percentage) */
+    x: number | string;
+    /** Y position (pixels or percentage) */
+    y: number | string;
+    /** Width (pixels or percentage) */
+    width?: number | string;
+    /** Height (pixels or percentage) */
+    height?: number | string;
+    /** Anchor point for positioning */
+    anchor?: 'center' | 'top-left' | 'top-right' | 'bottom-left' | 'bottom-right';
+}
+/**
+ * Text styling options.
+ */
+export interface TextStyle {
+    /** Font size in pixels */
+    fontSize: number;
+    /** Font family (defaults to system sans-serif) */
+    fontFamily?: string;
+    /** Font weight */
+    fontWeight?: 'normal' | 'bold';
+    /** Text color (CSS color) */
+    color: string;
+    /** Text alignment */
+    textAlign?: 'left' | 'center' | 'right';
+    /** Line height multiplier */
+    lineHeight?: number;
+    /** Add drop shadow for readability over images */
+    shadow?: boolean;
+    /** Background color for text box */
+    background?: string;
+    /** Padding around text (pixels) */
+    padding?: number;
+    /** Maximum number of lines before truncation (adds "..." to last line) */
+    maxLines?: number;
+}
+/**
+ * Animation to apply to a layer.
+ */
+export interface Animation {
+    /** Animation type */
+    type: AnimationType;
+    /** Duration in seconds (defaults to layer's block duration) */
+    duration?: number;
+    /** Delay before animation starts (seconds) */
+    delay?: number;
+    /** CSS easing function */
+    easing?: string;
+    /** For Ken Burns: zoom direction */
+    direction?: 'in' | 'out';
+    /** For pan animations: pan direction */
+    panDirection?: 'left' | 'right' | 'up' | 'down';
+}
+/**
+ * Available animation types.
+ */
+export type AnimationType = 'none' | 'fadeIn' | 'fadeOut' | 'slowZoom' | 'zoomIn' | 'zoomOut' | 'panLeft' | 'panRight' | 'typewriter';
+/**
+ * Transition between blocks.
+ */
+export interface Transition {
+    /** Transition type */
+    type: TransitionType;
+    /** Duration in seconds */
+    duration: number;
+}
+export type TransitionType = 'cut' | 'fade' | 'dissolve' | 'slideLeft' | 'slideRight';
+/**
+ * Audio track configuration.
+ * Articles have multiple MP3 segments (intro + sections).
+ */
+export interface AudioTrack {
+    /** Audio segments in playback order */
+    segments: AudioSegment[];
+}
+/**
+ * A single caption phrase to display during playback.
+ */
+export interface CaptionPhrase {
+    /** The text to display */
+    text: string;
+    /** Start time in seconds (relative to doc start) */
+    startTime: number;
+    /** End time in seconds */
+    endTime: number;
+    /** Which audio segment this caption belongs to (0-indexed) */
+    audioSegment: number;
+}
+/**
+ * Caption track for a doc.
+ */
+export interface CaptionTrack {
+    /** Caption phrases in chronological order */
+    phrases: CaptionPhrase[];
+    /** When the captions were generated */
+    generatedAt: string;
+    /** Algorithm version for regeneration detection */
+    version: number;
+}
+/**
+ * A single audio segment (one MP3 file).
+ */
+export interface AudioSegment {
+    /** Path to MP3 file (relative to article media dir) */
+    src: string;
+    /** Segment name (e.g., "intro", "history") */
+    name: string;
+    /** Duration in seconds */
+    duration: number;
+    /** Start time in overall timeline (calculated) */
+    startTime: number;
+}
+/**
+ * Calculate total duration from audio segments.
+ */
+export declare function calculateDuration(audio: AudioTrack): number;
+/**
+ * Find which audio segment is playing at a given time.
+ */
+export declare function getSegmentAtTime(audio: AudioTrack, time: number): number;
+/**
+ * Find which block should be visible at a given time.
+ */
+export declare function getBlockAtTime(blocks: Block[], time: number): Block | null;
+/**
+ * Find the caption phrase that should be displayed at a given time.
+ */
+export declare function getCaptionAtTime(captions: CaptionTrack | undefined, time: number): CaptionPhrase | null;
+/**
+ * Validate a Doc for completeness.
+ */
+export declare function validateDoc(script: Doc): string[];
+export {};
+//# sourceMappingURL=Doc.d.ts.map

package/dist/schemas/Doc.d.ts.map

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

package/dist/schemas/Doc.js

@@ -0,0 +1,90 @@
+/**
+ * Doc Schema
+ *
+ * Defines the JSON format for AI-scriptable visual docs that accompany
+ * audio narration. A Doc describes a sequence of animated blocks
+ * with text overlays, images, and transitions synchronized to audio.
+ *
+ * The format is designed to be:
+ * 1. AI-generatable - Claude can create scripts from article content
+ * 2. Browser-renderable - SVG + CSS animations (ES2015 compatible)
+ * 3. Video-exportable - Frame-by-frame capture via Playwright
+ *
+ * Timing: Blocks are timed to match narration audio segments. Each article
+ * has 3-6 MP3 files (intro + sections), and blocks are grouped by segment.
+ */
+// ============================================
+// Helper Functions
+// ============================================
+/**
+ * Calculate total duration from audio segments.
+ */
+export function calculateDuration(audio) {
+    return audio.segments.reduce((sum, seg) => sum + seg.duration, 0);
+}
+/**
+ * Find which audio segment is playing at a given time.
+ */
+export function getSegmentAtTime(audio, time) {
+    let elapsed = 0;
+    for (let i = 0; i < audio.segments.length; i++) {
+        elapsed += audio.segments[i].duration;
+        if (time < elapsed)
+            return i;
+    }
+    return audio.segments.length - 1;
+}
+/**
+ * Find which block should be visible at a given time.
+ */
+export function getBlockAtTime(blocks, time) {
+    for (let i = blocks.length - 1; i >= 0; i--) {
+        const block = blocks[i];
+        if (time >= block.startTime && time < block.startTime + block.duration) {
+            return block;
+        }
+    }
+    return blocks[0] || null;
+}
+/**
+ * Find the caption phrase that should be displayed at a given time.
+ */
+export function getCaptionAtTime(captions, time) {
+    if (!captions || !captions.phrases.length)
+        return null;
+    for (const phrase of captions.phrases) {
+        if (time >= phrase.startTime && time < phrase.endTime) {
+            return phrase;
+        }
+    }
+    return null;
+}
+/**
+ * Validate a Doc for completeness.
+ */
+export function validateDoc(script) {
+    const errors = [];
+    if (!script.articleId) {
+        errors.push('Missing articleId');
+    }
+    if (!script.blocks || script.blocks.length === 0) {
+        errors.push('No blocks defined');
+    }
+    if (!script.audio || !script.audio.segments || script.audio.segments.length === 0) {
+        errors.push('No audio segments defined');
+    }
+    // Check for gaps in block coverage
+    const totalDuration = script.duration;
+    let covered = 0;
+    for (const block of script.blocks) {
+        if (block.startTime > covered + 0.1) {
+            errors.push(`Gap in blocks: ${covered}s to ${block.startTime}s`);
+        }
+        covered = Math.max(covered, block.startTime + block.duration);
+    }
+    if (covered < totalDuration - 0.1) {
+        errors.push(`Blocks end at ${covered}s but audio is ${totalDuration}s`);
+    }
+    return errors;
+}
+//# sourceMappingURL=Doc.js.map

package/dist/schemas/Doc.js.map

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

package/dist/schemas/LayoutStrategy.d.ts

@@ -0,0 +1,84 @@
+/**
+ * Layout Strategy
+ *
+ * Provides orientation-specific layout hints for slide templates.
+ * Templates use these hints to position content appropriately for
+ * different aspect ratios (landscape, portrait, square).
+ *
+ * Key adaptations by orientation:
+ * - Portrait: Larger relative text, stacked layouts instead of side-by-side
+ * - Square: Balanced layout with moderate adjustments
+ * - Landscape: Default/reference layout
+ */
+import type { ViewportOrientation, ViewportConfig } from './Viewport.js';
+/**
+ * Layout hints for template positioning based on orientation.
+ */
+export interface LayoutHints {
+    /** Primary content Y position (percentage string, e.g., "35%") */
+    primaryY: string;
+    /** Secondary content Y position (percentage string) */
+    secondaryY: string;
+    /** Tertiary/detail Y position (percentage string) */
+    tertiaryY: string;
+    /** Title font size multiplier (relative to base) */
+    titleScale: number;
+    /** Body text font size multiplier (relative to base) */
+    bodyScale: number;
+    /** Two-column: left X position (percentage string) */
+    columnLeftX: string;
+    /** Two-column: right X position (percentage string) */
+    columnRightX: string;
+    /** Two-column in portrait: top Y position for stacked layout */
+    columnTopY: string;
+    /** Two-column in portrait: bottom Y position for stacked layout */
+    columnBottomY: string;
+    /** Whether two-column should stack vertically */
+    stackColumns: boolean;
+    /** Max text width (percentage string) for wrapping */
+    maxTextWidth: string;
+    /** Horizontal padding from edges (percentage string) */
+    horizontalPadding: string;
+    /** Caption position Y for imageWithCaption (percentage string) */
+    captionY: string;
+    /** Caption font size multiplier */
+    captionScale: number;
+}
+/**
+ * Get layout hints for a given orientation.
+ */
+export declare function getLayoutHints(orientation: ViewportOrientation): LayoutHints;
+/**
+ * Calculate a scaled font size based on viewport and layout hints.
+ *
+ * @param basePx - Base font size in pixels (designed for 1920x1080)
+ * @param viewport - Target viewport configuration
+ * @param orientation - Viewport orientation
+ * @param isTitle - Whether this is title text (uses titleScale) or body (uses bodyScale)
+ */
+export declare function scaledFontSize(basePx: number, viewport: ViewportConfig, orientation: ViewportOrientation, isTitle?: boolean): number;
+/**
+ * Get position for two-column layout based on orientation.
+ * Returns { left: {x, y}, right: {x, y} } positions.
+ */
+export declare function getTwoColumnPositions(orientation: ViewportOrientation): {
+    left: {
+        x: string;
+        y: string;
+    };
+    right: {
+        x: string;
+        y: string;
+    };
+};
+/**
+ * Get safe text bounds for a given orientation.
+ * Returns margins to keep text away from edges.
+ */
+export declare function getSafeTextBounds(orientation: ViewportOrientation): {
+    left: string;
+    right: string;
+    top: string;
+    bottom: string;
+};
+//# sourceMappingURL=LayoutStrategy.d.ts.map

package/dist/schemas/LayoutStrategy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"LayoutStrategy.d.ts","sourceRoot":"","sources":["../../src/schemas/LayoutStrategy.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAE,mBAAmB,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAGzE;;GAEG;AACH,MAAM,WAAW,WAAW;IAC1B,kEAAkE;IAClE,QAAQ,EAAE,MAAM,CAAC;IACjB,uDAAuD;IACvD,UAAU,EAAE,MAAM,CAAC;IACnB,qDAAqD;IACrD,SAAS,EAAE,MAAM,CAAC;IAClB,oDAAoD;IACpD,UAAU,EAAE,MAAM,CAAC;IACnB,wDAAwD;IACxD,SAAS,EAAE,MAAM,CAAC;IAClB,sDAAsD;IACtD,WAAW,EAAE,MAAM,CAAC;IACpB,uDAAuD;IACvD,YAAY,EAAE,MAAM,CAAC;IACrB,gEAAgE;IAChE,UAAU,EAAE,MAAM,CAAC;IACnB,mEAAmE;IACnE,aAAa,EAAE,MAAM,CAAC;IACtB,iDAAiD;IACjD,YAAY,EAAE,OAAO,CAAC;IACtB,sDAAsD;IACtD,YAAY,EAAE,MAAM,CAAC;IACrB,wDAAwD;IACxD,iBAAiB,EAAE,MAAM,CAAC;IAC1B,kEAAkE;IAClE,QAAQ,EAAE,MAAM,CAAC;IACjB,mCAAmC;IACnC,YAAY,EAAE,MAAM,CAAC;CACtB;AA4DD;;GAEG;AACH,wBAAgB,cAAc,CAAC,WAAW,EAAE,mBAAmB,GAAG,WAAW,CAE5E;AAED;;;;;;;GAOG;AACH,wBAAgB,cAAc,CAC5B,MAAM,EAAE,MAAM,EACd,QAAQ,EAAE,cAAc,EACxB,WAAW,EAAE,mBAAmB,EAChC,OAAO,GAAE,OAAe,GACvB,MAAM,CAKR;AAED;;;GAGG;AACH,wBAAgB,qBAAqB,CAAC,WAAW,EAAE,mBAAmB,GAAG;IACvE,IAAI,EAAE;QAAE,CAAC,EAAE,MAAM,CAAC;QAAC,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IAC/B,KAAK,EAAE;QAAE,CAAC,EAAE,MAAM,CAAC;QAAC,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;CACjC,CAgBA;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,WAAW,EAAE,mBAAmB,GAAG;IACnE,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,GAAG,EAAE,MAAM,CAAC;IACZ,MAAM,EAAE,MAAM,CAAC;CAChB,CAQA"}