@bendyline/squisq 1.0.1 → 1.1.1

package/dist/transform/templateSelector.js

@@ -0,0 +1,218 @@
+/**
+ * Template Selector
+ *
+ * Selects which extracted elements to promote to visual template blocks
+ * and handles color scheme rotation, image interleaving, and template
+ * variety. Ported and generalized from qualla-internal's TemplateSelector.
+ */
+import { mapElementToBlock } from '../generate/templateMapper.js';
+import { SeededRandom } from '../random/SeededRandom.js';
+/** Accent positions to rotate through. */
+const ACCENT_POSITIONS = [
+    'left-strip',
+    'right-strip',
+    'bottom-strip',
+    'corner-inset',
+];
+/** Ambient motions to rotate on image blocks. */
+const AMBIENT_MOTIONS = [
+    'zoomIn',
+    'zoomOut',
+    'panLeft',
+    'panRight',
+];
+/**
+ * Select extractions and build a transformed block sequence.
+ *
+ * @param analyzed - Analyzed blocks from blockAnalyzer.
+ * @param config - The transform style configuration.
+ * @param images - Available images for interleaving.
+ * @param seed - Random seed for deterministic output.
+ */
+export function selectAndBuild(analyzed, config, images, seed) {
+    const rng = new SeededRandom(seed);
+    // 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));
+    const selected = candidates.slice(0, maxTransforms);
+    // 3. Build the output block sequence
+    const result = buildBlockSequence(analyzed, selected, config, images, rng);
+    return result;
+}
+/**
+ * Collect candidate extractions from all analyzed blocks, sorted by
+ * a combined score of confidence and type preference.
+ */
+function collectCandidates(analyzed, config) {
+    const candidates = [];
+    for (let i = 0; i < analyzed.length; i++) {
+        const ab = analyzed[i];
+        // Skip blocks with no meaningful text
+        if (ab.bodyWordCount < 5)
+            continue;
+        for (const element of ab.extractions) {
+            if (element.confidence < config.minConfidence)
+                continue;
+            candidates.push({
+                element,
+                sourceBlock: ab.block,
+                sourceIndex: i,
+            });
+        }
+    }
+    // Sort by: preferred type rank (lower = better), then confidence (higher = better)
+    const typeRank = new Map(config.preferredTypes.map((t, i) => [t, i]));
+    const maxRank = config.preferredTypes.length;
+    candidates.sort((a, b) => {
+        const rankA = typeRank.get(a.element.type) ?? maxRank;
+        const rankB = typeRank.get(b.element.type) ?? maxRank;
+        if (rankA !== rankB)
+            return rankA - rankB;
+        return b.element.confidence - a.element.confidence;
+    });
+    // Deduplicate: if the same extracted text appears multiple times
+    // (e.g., from overlapping parent/child blocks), keep only the
+    // highest-ranked occurrence.
+    const seenTexts = new Set();
+    const deduplicated = [];
+    for (const candidate of candidates) {
+        const key = candidate.element.text.trim().toLowerCase();
+        if (seenTexts.has(key))
+            continue;
+        seenTexts.add(key);
+        deduplicated.push(candidate);
+    }
+    return deduplicated;
+}
+/**
+ * Build the output block sequence, replacing source blocks with template
+ * blocks where extractions were selected, and interleaving images.
+ */
+function buildBlockSequence(analyzed, selected, config, images, rng) {
+    // Map: sourceIndex → list of selected extractions for that block
+    const blockExtractions = new Map();
+    for (const sel of selected) {
+        const list = blockExtractions.get(sel.sourceIndex) ?? [];
+        list.push(sel);
+        blockExtractions.set(sel.sourceIndex, list);
+    }
+    // Limit extractions per block: cap at blocksPerSection.max and ensure
+    // template type variety within each block (no two same-type extractions).
+    for (const [idx, list] of blockExtractions) {
+        const diverse = [];
+        const usedTypes = new Set();
+        for (const sel of list) {
+            if (usedTypes.has(sel.element.type))
+                continue;
+            usedTypes.add(sel.element.type);
+            diverse.push(sel);
+            if (diverse.length >= config.blocksPerSection.max)
+                break;
+        }
+        blockExtractions.set(idx, diverse);
+    }
+    const blocks = [];
+    let transformedCount = 0;
+    let insertedCount = 0;
+    let colorIndex = 0;
+    let blockIdCounter = 0;
+    let imageIndex = 0;
+    let accentPositionIndex = 0;
+    let elementsSinceImage = 0;
+    let prevTemplateType = '';
+    // Calculate image interleaving interval
+    const totalTransformed = Array.from(blockExtractions.values()).reduce((sum, list) => sum + list.length, 0);
+    const imageInterval = config.interleaveImages && images.length > 0 && totalTransformed > 0
+        ? Math.max(2, Math.floor(totalTransformed / (images.length + 1)))
+        : Infinity;
+    for (let i = 0; i < analyzed.length; i++) {
+        const ab = analyzed[i];
+        const extractions = blockExtractions.get(i);
+        if (!extractions || extractions.length === 0) {
+            // Keep the original block unchanged
+            blocks.push(ab.block);
+            continue;
+        }
+        // Insert section header before a group of transformed blocks (if enabled)
+        if (config.insertSectionHeaders && ab.block.title) {
+            const headerBlock = {
+                template: 'sectionHeader',
+                id: `transform-header-${blockIdCounter++}`,
+                duration: ab.block.duration > 0 ? Math.min(3, ab.block.duration * 0.2) : 3,
+                audioSegment: ab.block.audioSegment,
+                title: ab.block.title,
+                colorScheme: config.colorSchemes[colorIndex % config.colorSchemes.length],
+            };
+            blocks.push(headerBlock);
+            insertedCount++;
+        }
+        // Convert each selected extraction to a template block.
+        // Track the last template used globally (not just within this block)
+        // to avoid consecutive same-template slides across the entire output.
+        for (const sel of extractions) {
+            const colorScheme = config.colorSchemes[colorIndex % config.colorSchemes.length];
+            // Build accent image if we have images in the pool
+            let accentImage;
+            if (images.length > 0 && config.interleaveImages) {
+                const img = images[imageIndex % images.length];
+                accentImage = {
+                    src: img.src,
+                    alt: img.alt ?? '',
+                    position: ACCENT_POSITIONS[accentPositionIndex % ACCENT_POSITIONS.length],
+                    ambientMotion: rng.pick(AMBIENT_MOTIONS) ?? 'zoomIn',
+                    credit: img.credit,
+                    license: img.license,
+                };
+                accentPositionIndex++;
+            }
+            const templateBlock = mapElementToBlock(sel.element, {
+                id: `transform-${blockIdCounter++}`,
+                duration: ab.block.duration > 0 ? ab.block.duration / extractions.length : 6,
+                audioSegment: ab.block.audioSegment,
+                colorScheme,
+                accentImage,
+                sourceStartTime: sel.element.sourcePosition,
+            });
+            // Apply transition based on style
+            if (config.transitionStyle !== 'cut') {
+                templateBlock.transition = {
+                    type: config.transitionStyle === 'mixed'
+                        ? (rng.pick(['fade', 'dissolve']) ?? 'fade')
+                        : config.transitionStyle,
+                    duration: 0.5,
+                };
+            }
+            // Avoid consecutive same-template blocks by bumping color for variety
+            if (templateBlock.template === prevTemplateType) {
+                colorIndex++;
+            }
+            prevTemplateType = templateBlock.template;
+            blocks.push(templateBlock);
+            transformedCount++;
+            colorIndex++;
+            elementsSinceImage++;
+            // Interleave standalone image at intervals
+            if (config.interleaveImages &&
+                imageIndex < images.length &&
+                elementsSinceImage >= imageInterval) {
+                const img = images[imageIndex];
+                const imageBlock = {
+                    template: 'imageWithCaption',
+                    id: `transform-img-${blockIdCounter++}`,
+                    duration: 4,
+                    audioSegment: ab.block.audioSegment,
+                    imageSrc: img.src,
+                    imageAlt: img.alt ?? '',
+                    ambientMotion: rng.pick(AMBIENT_MOTIONS) ?? 'zoomIn',
+                };
+                blocks.push(imageBlock);
+                imageIndex++;
+                insertedCount++;
+                elementsSinceImage = 0;
+            }
+        }
+    }
+    return { blocks, transformedCount, insertedCount };
+}
+//# sourceMappingURL=templateSelector.js.map

package/dist/transform/templateSelector.js.map

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

package/dist/transform/timingAllocator.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Timing Allocator
+ *
+ * Distributes timing (startTime, duration) across transformed blocks.
+ * When the source Doc has audio, blocks are fitted to the overall duration.
+ * When no audio is present, uses reading-time estimation.
+ */
+import type { Block } from '../schemas/Doc.js';
+import type { TemplateBlock } from '../schemas/BlockTemplates.js';
+/**
+ * Allocate startTime and duration across a mixed array of blocks and
+ * template blocks. Template blocks get timing assigned; existing blocks
+ * retain their original timing when possible.
+ *
+ * @param blocks - The output from templateSelector (mixed Block | TemplateBlock).
+ * @param totalDuration - The Doc's total duration (from audio or estimation).
+ * @returns A new array of Blocks with consistent timing. Template blocks
+ *          are returned as Blocks (with startTime/duration set, layers empty).
+ */
+export declare function allocateTiming(blocks: Array<Block | TemplateBlock>, totalDuration: number): Block[];
+//# sourceMappingURL=timingAllocator.d.ts.map

package/dist/transform/timingAllocator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"timingAllocator.d.ts","sourceRoot":"","sources":["../../src/transform/timingAllocator.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,mBAAmB,CAAC;AAC/C,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,8BAA8B,CAAC;AAUlE;;;;;;;;;GASG;AACH,wBAAgB,cAAc,CAC5B,MAAM,EAAE,KAAK,CAAC,KAAK,GAAG,aAAa,CAAC,EACpC,aAAa,EAAE,MAAM,GACpB,KAAK,EAAE,CA0DT"}

package/dist/transform/timingAllocator.js

@@ -0,0 +1,111 @@
+/**
+ * Timing Allocator
+ *
+ * Distributes timing (startTime, duration) across transformed blocks.
+ * When the source Doc has audio, blocks are fitted to the overall duration.
+ * When no audio is present, uses reading-time estimation.
+ */
+import { isTemplateBlock } from '../schemas/BlockTemplates.js';
+/** Minimum block duration in seconds. */
+const MIN_BLOCK_DURATION = 3;
+/** Maximum block duration in seconds. */
+const MAX_BLOCK_DURATION = 20;
+/** Default duration when no timing info is available. */
+const DEFAULT_BLOCK_DURATION = 6;
+/**
+ * Allocate startTime and duration across a mixed array of blocks and
+ * template blocks. Template blocks get timing assigned; existing blocks
+ * retain their original timing when possible.
+ *
+ * @param blocks - The output from templateSelector (mixed Block | TemplateBlock).
+ * @param totalDuration - The Doc's total duration (from audio or estimation).
+ * @returns A new array of Blocks with consistent timing. Template blocks
+ *          are returned as Blocks (with startTime/duration set, layers empty).
+ */
+export function allocateTiming(blocks, totalDuration) {
+    if (blocks.length === 0)
+        return [];
+    const effectiveDuration = totalDuration > 0 ? totalDuration : estimateDefaultDuration(blocks);
+    // First pass: assign raw durations
+    const durations = blocks.map((block) => {
+        if (!isTemplateBlock(block) && block.duration > 0) {
+            // Existing block with known duration — keep it
+            return block.duration;
+        }
+        if (isTemplateBlock(block) && block.duration > 0) {
+            return block.duration;
+        }
+        return DEFAULT_BLOCK_DURATION;
+    });
+    // Scale durations to fit the total
+    const rawTotal = durations.reduce((sum, d) => sum + d, 0);
+    if (rawTotal > 0 && effectiveDuration > 0) {
+        const scale = effectiveDuration / rawTotal;
+        for (let i = 0; i < durations.length; i++) {
+            durations[i] = clampDuration(durations[i] * scale);
+        }
+    }
+    // Second pass: assign startTimes and build output Blocks
+    let currentTime = 0;
+    const result = [];
+    for (let i = 0; i < blocks.length; i++) {
+        const block = blocks[i];
+        const duration = durations[i];
+        if (isTemplateBlock(block)) {
+            // Convert TemplateBlock to Block shell, preserving all template-specific
+            // fields (stat, quote, description, etc.) so they survive through to
+            // the player's template expansion step.
+            const outputBlock = {
+                ...block,
+                startTime: currentTime,
+                duration,
+                title: getTemplateTitle(block),
+            };
+            result.push(outputBlock);
+        }
+        else {
+            // Existing block — update timing
+            result.push({
+                ...block,
+                startTime: currentTime,
+                duration,
+            });
+        }
+        currentTime += duration;
+    }
+    return result;
+}
+/** Clamp a duration to the min/max range. */
+function clampDuration(d) {
+    return Math.max(MIN_BLOCK_DURATION, Math.min(MAX_BLOCK_DURATION, d));
+}
+/** Estimate a total duration from block contents when no audio is available. */
+function estimateDefaultDuration(blocks) {
+    let totalSeconds = 0;
+    for (const block of blocks) {
+        if (!isTemplateBlock(block) && block.duration > 0) {
+            totalSeconds += block.duration;
+        }
+        else {
+            totalSeconds += DEFAULT_BLOCK_DURATION;
+        }
+    }
+    return Math.max(totalSeconds, blocks.length * MIN_BLOCK_DURATION);
+}
+/** Extract a display title from a template block if available. */
+function getTemplateTitle(block) {
+    if ('title' in block && typeof block.title === 'string') {
+        return block.title;
+    }
+    if ('stat' in block && typeof block.stat === 'string') {
+        return block.stat;
+    }
+    if ('fact' in block && typeof block.fact === 'string') {
+        return block.fact;
+    }
+    if ('quote' in block && typeof block.quote === 'string') {
+        return block.quote.slice(0, 60);
+    }
+    return undefined;
+}
+//# sourceMappingURL=timingAllocator.js.map

package/dist/transform/timingAllocator.js.map

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

package/dist/transform/types.d.ts

@@ -0,0 +1,86 @@
+/**
+ * Transform Types
+ *
+ * Defines the type system for doc block transforms — algorithms that take
+ * an existing Doc and produce a new Doc with blocks optimized for visual
+ * presentation. Transforms are read-only on the input and deterministic.
+ */
+import type { Doc } from '../schemas/Doc.js';
+import type { ExtractionType } from '../generate/contentExtractor.js';
+import type { ColorScheme } from '../schemas/BlockTemplates.js';
+/** Identifier for a registered transform style. */
+export type TransformStyleId = string;
+/** Summary info for UI dropdowns (mirrors getThemeSummaries pattern). */
+export interface TransformStyleSummary {
+    id: TransformStyleId;
+    name: string;
+    description: string;
+}
+/** Declarative configuration controlling how a style transforms content. */
+export interface TransformStyleConfig {
+    /** Unique style identifier. */
+    id: TransformStyleId;
+    /** Human-readable name for UI display. */
+    name: string;
+    /** Short description for UI tooltips. */
+    description: string;
+    /**
+     * Minimum confidence for extracted elements to become template blocks (0–1).
+     * Higher values = fewer but higher-quality transformations.
+     */
+    minConfidence: number;
+    /**
+     * Maximum fraction of blocks that get transformed (0–1).
+     * 0.2 = light touch, 0.8 = aggressive restructuring.
+     */
+    transformRatio: number;
+    /** Which extraction types this style prefers, in priority order. */
+    preferredTypes: ExtractionType[];
+    /** Color schemes to rotate through on template blocks. */
+    colorSchemes: ColorScheme[];
+    /** Whether to insert sectionHeader blocks between groups. */
+    insertSectionHeaders: boolean;
+    /** Whether to interleave imageWithCaption blocks when images are available. */
+    interleaveImages: boolean;
+    /** Target density of template blocks per section. */
+    blocksPerSection: {
+        min: number;
+        max: number;
+    };
+    /** Transition style preference for transformed blocks. */
+    transitionStyle: 'cut' | 'fade' | 'dissolve' | 'mixed';
+}
+/** Image metadata for image interleaving. */
+export interface TransformImage {
+    /** Image source path or URL. */
+    src: string;
+    /** Alt text for accessibility. */
+    alt?: string;
+    /** Photo credit. */
+    credit?: string;
+    /** License identifier. */
+    license?: string;
+}
+/** Options passed to `applyTransform()`. */
+export interface TransformOptions {
+    /** Deterministic seed. Default: hash of doc.articleId. */
+    seed?: number;
+    /** Available images for image interleaving / accent images. */
+    images?: TransformImage[];
+    /** Theme ID to embed in the output Doc. */
+    themeId?: string;
+    /** Override specific style config values. */
+    overrides?: Partial<TransformStyleConfig>;
+}
+/** Result of applying a transform. */
+export interface TransformResult {
+    /** The transformed Doc. Input doc is NOT mutated. */
+    doc: Doc;
+    /** Statistics about what changed. */
+    stats: {
+        totalInputBlocks: number;
+        transformedBlocks: number;
+        insertedBlocks: number;
+    };
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/transform/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/transform/types.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,mBAAmB,CAAC;AAC7C,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,iCAAiC,CAAC;AACtE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,8BAA8B,CAAC;AAIhE,mDAAmD;AACnD,MAAM,MAAM,gBAAgB,GAAG,MAAM,CAAC;AAEtC,yEAAyE;AACzE,MAAM,WAAW,qBAAqB;IACpC,EAAE,EAAE,gBAAgB,CAAC;IACrB,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;CACrB;AAID,4EAA4E;AAC5E,MAAM,WAAW,oBAAoB;IACnC,+BAA+B;IAC/B,EAAE,EAAE,gBAAgB,CAAC;IACrB,0CAA0C;IAC1C,IAAI,EAAE,MAAM,CAAC;IACb,yCAAyC;IACzC,WAAW,EAAE,MAAM,CAAC;IAEpB;;;OAGG;IACH,aAAa,EAAE,MAAM,CAAC;IAEtB;;;OAGG;IACH,cAAc,EAAE,MAAM,CAAC;IAEvB,oEAAoE;IACpE,cAAc,EAAE,cAAc,EAAE,CAAC;IAEjC,0DAA0D;IAC1D,YAAY,EAAE,WAAW,EAAE,CAAC;IAE5B,6DAA6D;IAC7D,oBAAoB,EAAE,OAAO,CAAC;IAE9B,+EAA+E;IAC/E,gBAAgB,EAAE,OAAO,CAAC;IAE1B,qDAAqD;IACrD,gBAAgB,EAAE;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,MAAM,CAAA;KAAE,CAAC;IAE/C,0DAA0D;IAC1D,eAAe,EAAE,KAAK,GAAG,MAAM,GAAG,UAAU,GAAG,OAAO,CAAC;CACxD;AAID,6CAA6C;AAC7C,MAAM,WAAW,cAAc;IAC7B,gCAAgC;IAChC,GAAG,EAAE,MAAM,CAAC;IACZ,kCAAkC;IAClC,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,oBAAoB;IACpB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,0BAA0B;IAC1B,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,4CAA4C;AAC5C,MAAM,WAAW,gBAAgB;IAC/B,0DAA0D;IAC1D,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,+DAA+D;IAC/D,MAAM,CAAC,EAAE,cAAc,EAAE,CAAC;IAC1B,2CAA2C;IAC3C,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,6CAA6C;IAC7C,SAAS,CAAC,EAAE,OAAO,CAAC,oBAAoB,CAAC,CAAC;CAC3C;AAID,sCAAsC;AACtC,MAAM,WAAW,eAAe;IAC9B,qDAAqD;IACrD,GAAG,EAAE,GAAG,CAAC;IACT,qCAAqC;IACrC,KAAK,EAAE;QACL,gBAAgB,EAAE,MAAM,CAAC;QACzB,iBAAiB,EAAE,MAAM,CAAC;QAC1B,cAAc,EAAE,MAAM,CAAC;KACxB,CAAC;CACH"}

package/dist/transform/types.js

@@ -0,0 +1,9 @@
+/**
+ * Transform Types
+ *
+ * Defines the type system for doc block transforms — algorithms that take
+ * an existing Doc and produce a new Doc with blocks optimized for visual
+ * presentation. Transforms are read-only on the input and deterministic.
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/transform/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/transform/types.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG"}

package/dist/{types-DHiv_Pnm.d.ts → types-DYAzisMG.d.ts}

@@ -93,8 +93,10 @@ interface MarkdownNodeBase {
  * → `{ template: 'chart', params: { colorScheme: 'blue' } }`
  */
 interface HeadingTemplateAnnotation {
-    /** Template name (first token inside `{[…]}`) */
-    template: string;
+    /** Template name (first token inside `{[…]}`).
+     *  Optional when the annotation contains only key=value pairs
+     *  (e.g., `{[audio=intro.mp3]}`). */
+    template?: string;
     /** Optional key-value parameters (remaining `key=value` tokens) */
     params?: Record<string, string>;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bendyline/squisq",
-  "version": "1.0.1",
+  "version": "1.1.1",
   "description": "Headless utilities for doc/block rendering, spatial math, Markdown, and storage",
   "license": "MIT",
   "author": "Bendyline",
@@ -80,6 +80,11 @@
       "types": "./dist/generate/index.d.ts",
       "import": "./dist/generate/index.js",
       "default": "./dist/generate/index.js"
+    },
+    "./transform": {
+      "types": "./dist/transform/index.d.ts",
+      "import": "./dist/transform/index.js",
+      "default": "./dist/transform/index.js"
     }
   },
   "scripts": {