@bendyline/squisq 0.1.1

package/src/doc/docToMarkdown.ts

@@ -0,0 +1,98 @@
+/**
+ * Doc → Markdown Conversion
+ *
+ * Converts a Doc with a heading-driven Block hierarchy back into a
+ * MarkdownDocument. This is the reverse of markdownToDoc() and enables
+ * round-tripping: edit a Doc's block tree, then serialize back to markdown.
+ *
+ * **Algorithm:**
+ * Walk the block tree depth-first. For each block:
+ * 1. If it has a `sourceHeading`, emit that heading node
+ * 2. Emit all nodes in `contents`
+ * 3. Recurse into `children`
+ *
+ * @example
+ * ```ts
+ * import { markdownToDoc, docToMarkdown } from '@bendyline/squisq/doc';
+ * import { parseMarkdown, stringifyMarkdown } from '@bendyline/squisq/markdown';
+ *
+ * const md = '# Hello\n\nWorld\n';
+ * const doc = markdownToDoc(parseMarkdown(md));
+ * const roundTripped = stringifyMarkdown(docToMarkdown(doc));
+ * ```
+ */
+
+import type { Doc, Block } from '../schemas/Doc.js';
+import type { MarkdownDocument, MarkdownBlockNode, MarkdownHeading } from '../markdown/types.js';
+
+/**
+ * Convert a Doc with heading-driven blocks back to a MarkdownDocument.
+ *
+ * Walks the block tree depth-first, emitting heading nodes and contents
+ * in document order. Blocks without a `sourceHeading` (preamble blocks)
+ * emit only their contents.
+ *
+ * If a block has a `template` or `templateOverrides` that aren't already
+ * reflected in the heading's `templateAnnotation`, the annotation is
+ * injected so the round-trip preserves template assignments.
+ *
+ * @param doc - A Doc whose blocks may have `sourceHeading`, `contents`, and `children`
+ * @returns A MarkdownDocument that can be stringified back to markdown
+ */
+export function docToMarkdown(doc: Doc): MarkdownDocument {
+  const children: MarkdownBlockNode[] = [];
+
+  function emitBlock(block: Block): void {
+    // Emit the heading node if present
+    if (block.sourceHeading) {
+      const heading = ensureAnnotation(block, block.sourceHeading);
+      children.push(heading);
+    }
+
+    // Emit body content
+    if (block.contents) {
+      children.push(...block.contents);
+    }
+
+    // Recurse into children (sub-headings)
+    if (block.children) {
+      for (const child of block.children) {
+        emitBlock(child);
+      }
+    }
+  }
+
+  for (const block of doc.blocks) {
+    emitBlock(block);
+  }
+
+  return {
+    type: 'document',
+    children,
+  };
+}
+
+/**
+ * Ensure the heading's `templateAnnotation` reflects the block's
+ * template and templateOverrides. Returns a (possibly cloned) heading.
+ */
+function ensureAnnotation(block: Block, heading: MarkdownHeading): MarkdownHeading {
+  // If the heading already has an annotation, trust it (it came from parsing)
+  if (heading.templateAnnotation) return heading;
+
+  // If the block has a non-default template or overrides, inject an annotation
+  const hasExplicitTemplate = block.template && block.template !== 'sectionHeader';
+  const hasOverrides = block.templateOverrides && Object.keys(block.templateOverrides).length > 0;
+
+  if (!hasExplicitTemplate && !hasOverrides) return heading;
+
+  // Clone to avoid mutating the original
+  return {
+    ...heading,
+    children: [...heading.children],
+    templateAnnotation: {
+      template: block.template ?? 'sectionHeader',
+      ...(hasOverrides ? { params: block.templateOverrides } : {}),
+    },
+  };
+}

package/src/doc/getLayers.ts

@@ -0,0 +1,152 @@
+/**
+ * getLayers — Compute visual layers for a block on demand.
+ *
+ * This is the preferred way to obtain renderable layers for a block.
+ * Instead of storing pre-computed layers on the Block object, call
+ * `getLayers(block, context)` to derive them from the block's template
+ * name, content, and the current render context (theme, viewport, etc.).
+ *
+ * For raw blocks that already carry a `layers` array, those layers are
+ * returned directly (with optional persistent layer injection).
+ *
+ * @example
+ * ```ts
+ * import { getLayers } from '@bendyline/squisq/doc';
+ *
+ * const layers = getLayers(block, {
+ *   theme: DEFAULT_THEME,
+ *   viewport: VIEWPORT_PRESETS.landscape,
+ *   blockIndex: 0,
+ *   totalBlocks: 10,
+ * });
+ * ```
+ */
+
+import type { Block, Layer } from '../schemas/Doc.js';
+import type {
+  TemplateBlock,
+  TemplateContext,
+  PersistentLayerConfig,
+  DocBlock,
+} from '../schemas/BlockTemplates.js';
+import type { Theme } from '../schemas/Theme.js';
+import type { ViewportConfig } from '../schemas/Viewport.js';
+import { VIEWPORT_PRESETS } from '../schemas/Viewport.js';
+import { createTemplateContext, isTemplateBlock } from '../schemas/BlockTemplates.js';
+import { DEFAULT_THEME } from '../schemas/themeLibrary.js';
+import { templateRegistry } from './templates/index.js';
+import { expandPersistentLayers } from './templates/persistentLayers.js';
+
+// ============================================
+// RenderContext
+// ============================================
+
+/**
+ * Context needed to compute layers for a block.
+ *
+ * Captures the visual rendering parameters: theme colors, viewport
+ * configuration, persistent layers, and the block's position within
+ * the doc (for template functions that vary output by index).
+ */
+export interface RenderContext {
+  /** Theme for template rendering. Defaults to DEFAULT_THEME (documentary). */
+  theme?: Theme;
+
+  /** Target viewport configuration. Defaults to 16:9 landscape. */
+  viewport?: ViewportConfig;
+
+  /** Persistent layers injected behind and/or on top of all block content. */
+  persistentLayers?: PersistentLayerConfig;
+
+  /** 0-based index of this block in the sequence. Defaults to 0. */
+  blockIndex?: number;
+
+  /** Total number of blocks in the doc. Defaults to 1. */
+  totalBlocks?: number;
+}
+
+// ============================================
+// getLayers
+// ============================================
+
+/**
+ * Compute the visual layers for a block.
+ *
+ * Resolution order:
+ * 1. If the block already has a non-empty `layers` array, use it (raw block).
+ * 2. If the block has a `template` name that exists in the registry,
+ *    call the template function to generate layers.
+ * 3. Otherwise return an empty array.
+ *
+ * Persistent layers (bottom/top) from the render context are injected
+ * around the result unless the block opts out via `useBottomLayer: false`
+ * or `useTopLayer: false`.
+ *
+ * @param block   A Block or TemplateBlock to render.
+ * @param context Render context (theme, viewport, persistent layers, position).
+ * @returns The computed Layer[] for the block, ready for BlockRenderer.
+ */
+export function getLayers(block: DocBlock, context: RenderContext = {}): Layer[] {
+  const theme = context.theme ?? DEFAULT_THEME;
+  const viewport = context.viewport ?? VIEWPORT_PRESETS.landscape;
+  const blockIndex = context.blockIndex ?? 0;
+  const totalBlocks = context.totalBlocks ?? 1;
+
+  // 1. Raw block path: block already has pre-computed layers
+  const existingLayers = (block as Block).layers;
+  if (existingLayers && existingLayers.length > 0 && !isTemplateBlock(block)) {
+    return injectPersistentLayers(existingLayers, block, context);
+  }
+
+  // 2. Template path: look up and call the template function
+  if (isTemplateBlock(block) && block.template in templateRegistry) {
+    const templateName = block.template as keyof typeof templateRegistry;
+    const templateCtx = createTemplateContext(theme, blockIndex, totalBlocks, viewport);
+    let layers: Layer[];
+    try {
+      // Each registry entry accepts its specific TemplateBlock variant; the
+      // discriminated union guarantees the shapes match at runtime.
+      const templateFn = templateRegistry[templateName] as (
+        input: TemplateBlock,
+        ctx: TemplateContext,
+      ) => Layer[];
+      layers = templateFn(block, templateCtx);
+      if (!Array.isArray(layers)) {
+        console.error(`Template ${templateName} did not return an array, got:`, typeof layers);
+        layers = [];
+      }
+    } catch (err: unknown) {
+      console.error(`Error expanding template ${templateName}:`, err);
+      layers = [];
+    }
+
+    return injectPersistentLayers(layers, block, context);
+  }
+
+  // 3. Fallback: no layers and no known template
+  return injectPersistentLayers([], block, context);
+}
+
+// ============================================
+// Internal helpers
+// ============================================
+
+/**
+ * Inject persistent bottom/top layers around the block's own layers,
+ * respecting per-block opt-out flags.
+ */
+function injectPersistentLayers(layers: Layer[], block: DocBlock, context: RenderContext): Layer[] {
+  const { persistentLayers } = context;
+  if (!persistentLayers) return layers;
+
+  const bottomLayers = expandPersistentLayers(persistentLayers.bottomLayers);
+  const topLayers = expandPersistentLayers(persistentLayers.topLayers);
+
+  if (bottomLayers.length === 0 && topLayers.length === 0) return layers;
+
+  const templateBlock = block as TemplateBlock;
+  const useBottom = templateBlock.useBottomLayer !== false;
+  const useTop = templateBlock.useTopLayer !== false;
+
+  return [...(useBottom ? bottomLayers : []), ...layers, ...(useTop ? topLayers : [])];
+}

package/src/doc/index.ts

@@ -0,0 +1,8 @@
+export * from './templates/index.js';
+export * from './utils/animationUtils.js';
+export * from './utils/themeUtils.js';
+export { markdownToDoc, flattenBlocks, countBlocks, getBlockDepth } from './markdownToDoc.js';
+export type { MarkdownToDocOptions } from './markdownToDoc.js';
+export { docToMarkdown } from './docToMarkdown.js';
+export { getLayers } from './getLayers.js';
+export type { RenderContext } from './getLayers.js';

package/src/doc/markdownToDoc.ts

@@ -0,0 +1,277 @@
+/**
+ * Markdown → Doc Conversion
+ *
+ * Converts a MarkdownDocument into a hierarchical Doc whose Block tree
+ * mirrors the heading structure of the markdown. Every heading (H1–H6)
+ * becomes a Block; body content between headings populates `contents`;
+ * sub-headings nest as `children`.
+ *
+ * This enables using BlockTemplates to supply alternate visualizations
+ * for each section of a markdown document.
+ *
+ * @example
+ * ```ts
+ * import { parseMarkdown } from '@bendyline/squisq/markdown';
+ * import { markdownToDoc } from '@bendyline/squisq/doc';
+ *
+ * const md = parseMarkdown('# Intro\n\nHello world\n\n## Details\n\nMore text');
+ * const doc = markdownToDoc(md);
+ * // doc.blocks[0].sourceHeading.depth === 1  ("# Intro")
+ * // doc.blocks[0].contents  → [paragraph("Hello world")]
+ * // doc.blocks[0].children[0].sourceHeading.depth === 2  ("## Details")
+ * ```
+ */
+
+import type { Doc, Block } from '../schemas/Doc.js';
+import type { MarkdownDocument, MarkdownBlockNode, MarkdownHeading } from '../markdown/types.js';
+import { extractPlainText } from '../markdown/utils.js';
+
+// ============================================
+// Options
+// ============================================
+
+/**
+ * Options for markdownToDoc().
+ */
+export interface MarkdownToDocOptions {
+  /** Article ID for the generated Doc. Default: 'markdown-doc' */
+  articleId?: string;
+
+  /** Default template name for heading blocks. Default: 'sectionHeader' */
+  defaultTemplate?: string;
+
+  /** Default duration per block in seconds. Default: 5 */
+  defaultDuration?: number;
+
+  /** Custom ID generator. Receives the heading node and its index. */
+  generateId?: (heading: MarkdownHeading, index: number) => string;
+}
+
+// ============================================
+// ID Generation
+// ============================================
+
+/**
+ * Convert text to a URL-friendly slug.
+ * "Getting Started & More" → "getting-started-more"
+ */
+const SLUG_NON_WORD_RE = /[^\w\s-]/g;
+const SLUG_SPACES_RE = /[\s_]+/g;
+const SLUG_MULTI_HYPHEN_RE = /-+/g;
+const SLUG_TRIM_HYPHEN_RE = /^-|-$/g;
+
+function slugify(text: string): string {
+  return (
+    text
+      .toLowerCase()
+      .replace(SLUG_NON_WORD_RE, '') // Remove non-word chars (except spaces and hyphens)
+      .replace(SLUG_SPACES_RE, '-') // Replace spaces/underscores with hyphens
+      .replace(SLUG_MULTI_HYPHEN_RE, '-') // Collapse multiple hyphens
+      .replace(SLUG_TRIM_HYPHEN_RE, '') || // Trim leading/trailing hyphens
+    'block'
+  ); // Fallback for empty result
+}
+
+/**
+ * Creates an ID generator that produces unique slugified IDs.
+ * Appends -2, -3, etc. for duplicate headings.
+ */
+function createIdGenerator() {
+  const used = new Map<string, number>();
+
+  return (heading: MarkdownHeading, _index: number): string => {
+    const text = extractPlainText(heading);
+    const base = slugify(text);
+    const count = used.get(base) ?? 0;
+    used.set(base, count + 1);
+
+    if (count === 0) return base;
+    return `${base}-${count + 1}`;
+  };
+}
+
+// ============================================
+// Core Conversion
+// ============================================
+
+/**
+ * Convert a MarkdownDocument into a Doc with a heading-driven Block hierarchy.
+ *
+ * **Algorithm:**
+ * 1. Walk the document's top-level children sequentially
+ * 2. Each MarkdownHeading starts a new block at its depth level
+ * 3. Non-heading nodes accumulate as `contents` on the current block
+ * 4. Sub-headings (deeper depth) nest as `children` of the current block
+ * 5. Same-level or shallower headings close the current block and start a sibling/ancestor
+ * 6. Content before the first heading goes into a "preamble" block with no sourceHeading
+ *
+ * @param markdownDoc - A parsed MarkdownDocument
+ * @param options - Conversion options
+ * @returns A Doc whose blocks mirror the markdown heading structure
+ */
+export function markdownToDoc(markdownDoc: MarkdownDocument, options?: MarkdownToDocOptions): Doc {
+  const articleId = options?.articleId ?? 'markdown-doc';
+  const defaultTemplate = options?.defaultTemplate ?? 'sectionHeader';
+  const defaultDuration = options?.defaultDuration ?? 5;
+  const generateId = options?.generateId ?? createIdGenerator();
+
+  const rootBlocks: Block[] = [];
+  let headingIndex = 0;
+
+  // Stack tracks the nesting context: each entry is a block and its heading depth.
+  // We push when we go deeper, pop when we come back up.
+  const stack: Array<{ block: Block; depth: number }> = [];
+
+  // Accumulator for content nodes that appear before any heading (preamble)
+  // or between the current heading and the next heading/sub-heading.
+  let pendingContents: MarkdownBlockNode[] = [];
+  let currentBlock: Block | null = null;
+
+  function flushContents() {
+    if (currentBlock && pendingContents.length > 0) {
+      currentBlock.contents = (currentBlock.contents ?? []).concat(pendingContents);
+      pendingContents = [];
+    }
+  }
+
+  function makeBlock(heading: MarkdownHeading | null): Block {
+    const id = heading ? generateId(heading, headingIndex++) : 'preamble';
+
+    // Use template from annotation if present, otherwise fall back to default
+    const annotation = heading?.templateAnnotation;
+    const template = annotation?.template ?? (heading ? defaultTemplate : undefined);
+
+    const block: Block = {
+      id,
+      startTime: 0,
+      duration: defaultDuration,
+      audioSegment: 0,
+      template,
+      ...(heading ? { sourceHeading: heading } : {}),
+    };
+
+    // Propagate key-value params from annotation to templateOverrides
+    if (annotation?.params) {
+      block.templateOverrides = annotation.params;
+    }
+
+    return block;
+  }
+
+  for (const node of markdownDoc.children) {
+    if (node.type === 'heading') {
+      const heading = node as MarkdownHeading;
+      const depth = heading.depth;
+
+      // Flush any accumulated content to the current block
+      flushContents();
+
+      // Create the new block for this heading
+      const newBlock = makeBlock(heading);
+
+      if (stack.length === 0) {
+        // If there's a preamble block with no heading, push it first
+        if (currentBlock && !currentBlock.sourceHeading) {
+          rootBlocks.push(currentBlock);
+        }
+
+        // This is a root-level block (or the first heading)
+        rootBlocks.push(newBlock);
+        stack.push({ block: newBlock, depth });
+      } else {
+        // Find where this heading fits in the hierarchy
+        // Pop blocks from the stack until we find a parent with lower depth
+        while (stack.length > 0 && stack[stack.length - 1].depth >= depth) {
+          stack.pop();
+        }
+
+        if (stack.length === 0) {
+          // Same level as root or shallower — new root block
+          rootBlocks.push(newBlock);
+          stack.push({ block: newBlock, depth });
+        } else {
+          // Deeper — child of the current stack top
+          const parent = stack[stack.length - 1].block;
+          if (!parent.children) parent.children = [];
+          parent.children.push(newBlock);
+          stack.push({ block: newBlock, depth });
+        }
+      }
+
+      currentBlock = newBlock;
+    } else {
+      // Non-heading block node — accumulate as content
+      if (!currentBlock) {
+        // Content before any heading → create preamble block
+        currentBlock = makeBlock(null);
+      }
+      pendingContents.push(node);
+    }
+  }
+
+  // Flush remaining content
+  flushContents();
+
+  // If we only had preamble content (no headings at all), push it
+  if (currentBlock && !currentBlock.sourceHeading && !rootBlocks.includes(currentBlock)) {
+    rootBlocks.push(currentBlock);
+  }
+
+  // Calculate basic timing
+  const allBlocks = flattenBlocks(rootBlocks);
+  let currentTime = 0;
+  for (const block of allBlocks) {
+    block.startTime = currentTime;
+    currentTime += block.duration;
+  }
+
+  return {
+    articleId,
+    duration: currentTime,
+    blocks: rootBlocks,
+    audio: {
+      segments: [],
+    },
+    ...(markdownDoc.frontmatter ? { frontmatter: markdownDoc.frontmatter } : {}),
+  };
+}
+
+// ============================================
+// Utilities
+// ============================================
+
+/**
+ * Flatten a nested block tree into a depth-first ordered array.
+ * Useful for calculating sequential timing or iterating all blocks.
+ */
+export function flattenBlocks(blocks: Block[]): Block[] {
+  const result: Block[] = [];
+  for (const block of blocks) {
+    result.push(block);
+    if (block.children) {
+      result.push(...flattenBlocks(block.children));
+    }
+  }
+  return result;
+}
+
+/**
+ * Count the total number of blocks in a nested tree (including children at all levels).
+ */
+export function countBlocks(blocks: Block[]): number {
+  let count = 0;
+  for (const block of blocks) {
+    count += 1;
+    if (block.children) {
+      count += countBlocks(block.children);
+    }
+  }
+  return count;
+}
+
+/**
+ * Get the heading depth for a block. Returns 0 for preamble blocks (no heading).
+ */
+export function getBlockDepth(block: Block): number {
+  return block.sourceHeading?.depth ?? 0;
+}