@bendyline/squisq 1.5.2 → 2.0.0

package/src/doc/customTemplatesFrontmatter.ts

@@ -29,10 +29,6 @@
  * payload and a structured array, so older documents load unchanged.
  * The first save migrates them to the compact form.
  *
- * The `encodeLayersForFrontmatter` / `decodeLayersFromFrontmatter` pair
- * handles a single Layer array for the editor's `dataLayers="…"` Pandoc
- * param path; that path stays base64 (it's a different, per-block
- * mechanism) and is re-exported here for locality.
  */
 
 import type { Layer } from '../schemas/Doc.js';
@@ -134,43 +130,6 @@ function isDefaultViewport(v: { width: number; height: number } | undefined): bo
   return !v || (v.width === DEFAULT_VIEWPORT.width && v.height === DEFAULT_VIEWPORT.height);
 }
 
-// ─── Single-Layer base64 codec (legacy `dataLayers` path) ───────────
-
-/**
- * Base64-encode a Layer array as JSON, UTF-8 safe. Used by the editor's
- * per-block `dataLayers="…"` Pandoc param (not the doc-level template
- * list, which uses the compact JSON above).
- *
- * `btoa` only accepts Latin1 strings — any character outside that range
- * (e.g. an em-dash in a description) throws — so we round through
- * `TextEncoder`. Works in Node ≥18 and browsers.
- */
-export function encodeLayersForFrontmatter(layers: readonly Layer[]): string {
-  return utf8ToBase64(JSON.stringify(layers));
-}
-
-/** Inverse of {@link encodeLayersForFrontmatter}. Returns [] on parse failure. */
-export function decodeLayersFromFrontmatter(encoded: string): Layer[] {
-  try {
-    const json = base64ToUtf8(encoded);
-    const parsed = JSON.parse(json);
-    return Array.isArray(parsed) ? (parsed as Layer[]) : [];
-  } catch {
-    return [];
-  }
-}
-
-/** UTF-8 safe `btoa` — uses TextEncoder so arbitrary Unicode round-trips. */
-function utf8ToBase64(str: string): string {
-  const bytes = new TextEncoder().encode(str);
-  if (typeof globalThis.btoa === 'function') {
-    let binary = '';
-    for (let i = 0; i < bytes.length; i++) binary += String.fromCharCode(bytes[i]);
-    return globalThis.btoa(binary);
-  }
-  return Buffer.from(bytes).toString('base64');
-}
-
 /** UTF-8 safe `atob`. */
 function base64ToUtf8(b64: string): string {
   if (typeof globalThis.atob === 'function') {

package/src/doc/docToMarkdown.ts

@@ -23,6 +23,7 @@
  */
 
 import type { Doc, Block } from '../schemas/Doc.js';
+import type { MediaClip } from '../schemas/Media.js';
 import type {
   MarkdownDocument,
   MarkdownBlockNode,
@@ -30,6 +31,7 @@ import type {
   MarkdownParagraph,
 } from '../markdown/types.js';
 import { serializeAnnotation } from '../markdown/attrTokens.js';
+import { flattenBlocks } from './markdownToDoc.js';
 import {
   FRONTMATTER_CUSTOM_TEMPLATES_KEY,
   writeCustomTemplatesToFrontmatter,
@@ -58,6 +60,29 @@ const TRANSITION_PARAM_KEYS = ['transition', 'transitionDuration', 'transitionDi
 export function docToMarkdown(doc: Doc): MarkdownDocument {
   const children: MarkdownBlockNode[] = [];
 
+  // Media clips were LIFTED out of block contents at parse time
+  // (`extractMediaFromContents`); re-insert their authoring annotations so
+  // the round-trip doesn't silently drop narration/clip references.
+  // Doc-anchored clips whose home block still exists ride back into that
+  // block's body; homeless ones (programmatic clips, or a preamble block
+  // that was dropped once emptied) emit at the document top — the
+  // canonical authored position.
+  const blockIds = new Set(flattenBlocks(doc.blocks).map((b) => b.id));
+  const docMediaByBlock = new Map<string, MediaClip[]>();
+  const homelessDocMedia: MediaClip[] = [];
+  for (const clip of doc.documentMedia ?? []) {
+    if (clip.origin && blockIds.has(clip.origin.blockId)) {
+      const list = docMediaByBlock.get(clip.origin.blockId) ?? [];
+      list.push(clip);
+      docMediaByBlock.set(clip.origin.blockId, list);
+    } else {
+      homelessDocMedia.push(clip);
+    }
+  }
+  for (const clip of homelessDocMedia) {
+    children.push(synthesizeMediaParagraph(clip));
+  }
+
   function emitBlock(block: Block): void {
     // Emit the heading node if present
     if (block.sourceHeading) {
@@ -71,8 +96,29 @@ export function docToMarkdown(doc: Doc): MarkdownDocument {
       children.push(synthesizeAnnotationParagraph(block));
     }
 
-    // Emit body content
-    if (block.contents) {
+    // Emit body content, with this block's media annotations re-inserted
+    // at their original positions. `origin.index` refers to the ORIGINAL
+    // contents array (which included every annotation), so ascending
+    // insertion into the stripped contents reproduces the source order.
+    const clips = [...(block.media ?? []), ...(docMediaByBlock.get(block.id) ?? [])];
+    if (clips.length > 0) {
+      const contents = [...(block.contents ?? [])];
+      const anchored = clips
+        .filter((clip) => clip.origin)
+        .sort((a, b) => a.origin!.index - b.origin!.index);
+      for (const clip of anchored) {
+        contents.splice(
+          Math.min(clip.origin!.index, contents.length),
+          0,
+          synthesizeMediaParagraph(clip),
+        );
+      }
+      // Origin-less block clips (programmatic) sit right under the heading.
+      for (const clip of clips.filter((c) => !c.origin).reverse()) {
+        contents.unshift(synthesizeMediaParagraph(clip));
+      }
+      children.push(...contents);
+    } else if (block.contents) {
       children.push(...block.contents);
     }
 
@@ -131,6 +177,28 @@ function synthesizeAnnotationParagraph(block: Block): MarkdownParagraph {
   return { type: 'paragraph', children: [{ type: 'text', value: text }] };
 }
 
+/**
+ * Re-synthesize the authoring paragraph for a media clip. The extraction
+ * kept the exact source text (`origin.raw`) — emit it verbatim so quoting,
+ * param order, and `mm:ss` time forms stay byte-stable. Programmatic clips
+ * (no raw) serialize canonically: src, anchor, then timing params.
+ */
+function synthesizeMediaParagraph(clip: MediaClip): MarkdownParagraph {
+  if (clip.origin?.raw) {
+    return { type: 'paragraph', children: [{ type: 'text', value: clip.origin.raw }] };
+  }
+  const params: Record<string, string> = { src: clip.src };
+  if (clip.anchor === 'document') params.anchor = 'document';
+  if (clip.startAt) params.startAt = String(clip.startAt);
+  if (clip.clipStart != null) params.clipStart = String(clip.clipStart);
+  if (clip.clipEnd != null) params.clipEnd = String(clip.clipEnd);
+  if (clip.spillover) params.spillover = 'true';
+  return {
+    type: 'paragraph',
+    children: [{ type: 'text', value: serializeAnnotation(clip.kind, params) }],
+  };
+}
+
 /**
  * Ensure the heading's `templateAnnotation` reflects the block's
  * template and templateOverrides. Returns a (possibly cloned) heading.

package/src/doc/index.ts

@@ -3,6 +3,7 @@ export * from './utils/animationUtils.js';
 export * from './utils/themeUtils.js';
 export * from './utils/applyRenderStyle.js';
 export * from './utils/imageTreatment.js';
+export * from './utils/diagramText.js';
 export * from './templateInputs.js';
 export * from './utils/shapeGeometry.js';
 export {
@@ -11,12 +12,12 @@ export {
   flattenRenderableBlocks,
   countBlocks,
   getBlockDepth,
+  getBlockBodyText,
+  getPinnedBlockMeta,
 } from './markdownToDoc.js';
 export type { MarkdownToDocOptions } from './markdownToDoc.js';
 export { docToMarkdown } from './docToMarkdown.js';
 export {
-  encodeLayersForFrontmatter,
-  decodeLayersFromFrontmatter,
   readCustomTemplatesFromFrontmatter,
   writeCustomTemplatesToFrontmatter,
   FRONTMATTER_CUSTOM_TEMPLATES_KEY,
@@ -27,9 +28,8 @@ export {
   FRONTMATTER_CUSTOM_THEMES_KEY,
 } from './customThemesFrontmatter.js';
 export { resolveThemeForDoc } from './resolveDocTheme.js';
-export { getLayers } from './getLayers.js';
-export type { RenderContext } from './getLayers.js';
 export { resolveAudioMapping, scoreTextSimilarity } from './audioMapping.js';
+export { applyNarrationTiming, type NarrationResolution } from './applyNarrationTiming.js';
 export {
   isDataFence,
   parseDataFence,
@@ -53,3 +53,75 @@ export type {
   TemplateInputDescriptor,
   TemplateParamFinding,
 } from './templates/inputDescriptors.js';
+export {
+  ASCII_CHAR_H,
+  ASCII_CHAR_W,
+  ASCII_DIAGRAM_FENCE_LANGS,
+  asciiCellToCanvas,
+  asciiDiagramFromBlocks,
+  asciiDiagramFromTemplateData,
+  asciiDiagramToTemplateData,
+  canvasToAsciiCell,
+  detectAsciiDiagram,
+  isAsciiDiagramFence,
+  isEligibleAsciiFenceLang,
+  isExplicitDiagramLang,
+  isRepairableDiagram,
+  parseAsciiDiagram,
+  renderAsciiDiagram,
+  repairAsciiDiagram,
+} from './asciiDiagram/index.js';
+export type {
+  AsciiDiagram,
+  AsciiDiagramDetection,
+  AsciiDiagramEdge,
+  AsciiDiagramNode,
+  RenderAsciiDiagramOptions,
+  RepairResult,
+} from './asciiDiagram/index.js';
+export {
+  ASCII_TIMELINE_FENCE_LANGS,
+  asciiTimelineToTemplateData,
+  detectAsciiTimeline,
+  isAsciiTimelineFence,
+  isEligibleAsciiTimelineFenceLang,
+  isExplicitTimelineLang,
+  isWrappedFlowTimelineSource,
+  parseAsciiTimeline,
+  parseAsciiTimelineWithStats,
+  parseWrappedFlowTimeline,
+  renderAsciiTimeline,
+} from './asciiTimeline/index.js';
+export type {
+  AsciiTimeline,
+  AsciiTimelineDetection,
+  AsciiTimelineEvent,
+  AsciiTimelineLink,
+  AsciiTimelineMarker,
+  AsciiTimelineSide,
+  AsciiTimelineStats,
+  AsciiTimelineStyle,
+  AsciiTimelineTrack,
+  DetectAsciiTimelineOptions,
+  RenderAsciiTimelineOptions,
+} from './asciiTimeline/index.js';
+export {
+  TREE_FENCE_LANGS,
+  detectTree,
+  findFirstList,
+  isEligibleTreeFenceLang,
+  isExplicitTreeLang,
+  isTreeFence,
+  parseTree,
+  renderTree,
+  treeFromMarkdownList,
+  treeFromTemplateData,
+  treeToTemplateData,
+} from './treeview/index.js';
+export type {
+  RenderTreeOptions,
+  Tree,
+  TreeDetection,
+  TreeItem,
+  TreeNode,
+} from './treeview/index.js';

package/src/doc/markdownToDoc.ts

@@ -35,6 +35,7 @@ import { readCustomThemesFromFrontmatter } from './customThemesFrontmatter.js';
 import type {
   MarkdownDocument,
   MarkdownBlockNode,
+  MarkdownCodeBlock,
   MarkdownHeading,
   MarkdownNode,
   HtmlNode,
@@ -49,6 +50,11 @@ import { extractTemplateBlocksFromContents } from './annotationBlocks.js';
 import type { ParsedAnnotation } from './standaloneAnnotation.js';
 import { profileBlockContents, pickAutoTemplate } from '../recommend/templates.js';
 import { deriveTemplateInputs } from './templateInputs.js';
+import { isEligibleAsciiFenceLang } from './asciiDiagram/detect.js';
+import { parseAsciiDiagram } from './asciiDiagram/parse.js';
+import { asciiDiagramToTemplateData } from './asciiDiagram/mapping.js';
+import { isEligibleAsciiTimelineFenceLang } from './asciiTimeline/detect.js';
+import { parseAsciiTimeline } from './asciiTimeline/parse.js';
 import type { MediaClip } from '../schemas/Media.js';
 
 // ============================================
@@ -222,6 +228,17 @@ function pinnedMeta(block: Block): CoercedBlockMeta {
   return {};
 }
 
+/**
+ * Public accessor for {@link pinnedMeta}: the timing/meta values an author
+ * pinned on a block (heading `{key=value}` attrs or `{[key=value]}`
+ * annotation params). Consumers use this to tell "author pinned this"
+ * from "derive it" — e.g. narration timing never overwrites a pinned
+ * `duration=`/`startTime=`.
+ */
+export function getPinnedBlockMeta(block: Block): CoercedBlockMeta {
+  return pinnedMeta(block);
+}
+
 /**
  * Rebuild a block list, lifting standalone `{[…]}` template annotations out of
  * each block's body into heading-less sibling blocks (recursing into children
@@ -408,6 +425,7 @@ export function markdownToDoc(markdownDoc: MarkdownDocument, options?: MarkdownT
     } = extractMediaFromContents(
       block.contents,
       (src, i) => `${block.id}-media-${i}-${src.replace(/[^a-zA-Z0-9]+/g, '-')}`,
+      block.id,
     );
     if (media.length > 0) block.media = media;
     if (docMedia.length > 0) documentMedia.push(...docMedia);
@@ -463,6 +481,16 @@ export function markdownToDoc(markdownDoc: MarkdownDocument, options?: MarkdownT
     applyStructuredData(block, diagnostics);
   }
 
+  // Explicitly diagram-annotated blocks whose body is a single eligible
+  // ASCII-art fence get nodes/edges derived from it — no detection
+  // threshold, the author asked for a diagram. Children-driven diagrams
+  // and author `json data` node lists win over the fence.
+  for (const block of allBlocks) {
+    applyAsciiDiagramData(block, diagnostics);
+    applyTimelineData(block, diagnostics);
+    applyTreeData(block, diagnostics);
+  }
+
   // Content-aware template auto-pick (default on): unannotated heading
   // blocks whose body carries a strong signal get the matching template
   // plus inputs derived from that body. Strict derivation — when the
@@ -472,6 +500,11 @@ export function markdownToDoc(markdownDoc: MarkdownDocument, options?: MarkdownT
     applyAutoTemplates(rootBlocks, resolveTemplateName(defaultTemplate), { featureIndex: 0 });
   }
 
+  // Timeline parsing is intentionally tolerant and can retain unresolved
+  // branch declarations as warnings. Surface those after auto-template
+  // selection so both explicit and auto-derived timeline blocks participate.
+  for (const block of allBlocks) collectTimelineWarnings(block, diagnostics);
+
   // Duplicate ids make connections and navigation ambiguous. Generated
   // slugs are already deduped; this catches author-pinned `{#id}` clashes.
   const seenIds = new Map<string, Block>();
@@ -709,6 +742,94 @@ function applyStructuredData(block: Block, diagnostics: DocDiagnostic[]): void {
   }
 }
 
+/**
+ * Fill `templateData.nodes`/`edges` for an explicitly `{[diagram]}`-annotated
+ * block whose body is exactly one eligible ASCII-art fence. Runs without the
+ * detection threshold (explicit annotation = author intent), unconditionally
+ * of the autoTemplates switches. The fence stays in `contents`, untouched.
+ */
+function applyAsciiDiagramData(block: Block, diagnostics: DocDiagnostic[]): void {
+  if (resolveTemplateName(block.template ?? '') !== 'diagram') return;
+  if (block.children && block.children.length > 0) return; // native children win
+  if (block.templateData && 'nodes' in block.templateData) return; // author data wins
+  const fences = (block.contents ?? []).filter((n): n is MarkdownCodeBlock => n.type === 'code');
+  if (fences.length !== 1 || !isEligibleAsciiFenceLang(fences[0].lang)) return;
+  const parsed = parseAsciiDiagram(fences[0].value);
+  if (parsed.nodes.length === 0) {
+    diagnostics.push({
+      severity: 'warning',
+      code: 'ascii-diagram-parse',
+      message: `Diagram block "${block.id}": code fence did not parse as an ASCII diagram`,
+      blockId: block.id,
+    });
+    return;
+  }
+  const { nodes, edges } = asciiDiagramToTemplateData(parsed);
+  block.templateData = { nodes, edges, ...block.templateData };
+}
+
+/**
+ * Fill `templateData.items` for an explicitly `{[tree]}`-annotated block
+ * whose body is one eligible ASCII tree fence (or a nested list). Runs
+ * without the detection threshold (explicit annotation = author intent).
+ */
+function applyTreeData(block: Block, diagnostics: DocDiagnostic[]): void {
+  if (resolveTemplateName(block.template ?? '') !== 'tree') return;
+  if (block.templateData && 'items' in block.templateData) return; // author data wins
+  const derived = deriveTemplateInputs('tree', block.title ?? '', block.contents);
+  if (!derived || !Array.isArray(derived.items) || derived.items.length === 0) {
+    diagnostics.push({
+      severity: 'warning',
+      code: 'tree-parse',
+      message: `Tree block "${block.id}": body did not parse as a tree`,
+      blockId: block.id,
+    });
+    return;
+  }
+  block.templateData = { ...derived, ...block.templateData };
+}
+
+/**
+ * Fill `templateData.tracks`/`links` for an explicitly `{[timeline]}`-
+ * annotated block whose body is one eligible ASCII timeline fence.
+ */
+function applyTimelineData(block: Block, diagnostics: DocDiagnostic[]): void {
+  if (resolveTemplateName(block.template ?? '') !== 'timeline') return;
+  if (block.templateData && 'tracks' in block.templateData) return; // author data wins
+  const derived = deriveTemplateInputs('timeline', block.title ?? '', block.contents);
+  if (!derived || !Array.isArray(derived.tracks) || derived.tracks.length === 0) {
+    diagnostics.push({
+      severity: 'warning',
+      code: 'timeline-parse',
+      message: `Timeline block "${block.id}": body did not parse as an ASCII timeline`,
+      blockId: block.id,
+    });
+    return;
+  }
+  block.templateData = { ...derived, ...block.templateData };
+}
+
+function collectTimelineWarnings(block: Block, diagnostics: DocDiagnostic[]): void {
+  if (resolveTemplateName(block.template ?? '') !== 'timeline') return;
+  if (!block.templateData || !('tracks' in block.templateData)) return;
+  const fences = (block.contents ?? []).filter(
+    (node): node is MarkdownCodeBlock =>
+      node.type === 'code' && isEligibleAsciiTimelineFenceLang(node.lang),
+  );
+  if (fences.length !== 1) return;
+  for (const warning of parseAsciiTimeline(fences[0].value).warnings) {
+    const unresolved = /^unresolved-link\((.+)\)$/.exec(warning);
+    diagnostics.push({
+      severity: 'warning',
+      code: unresolved ? 'timeline-unresolved-link' : 'timeline-parse-warning',
+      message: unresolved
+        ? `Timeline block "${block.id}": unresolved branch ${unresolved[1]}`
+        : `Timeline block "${block.id}": ${warning}`,
+      blockId: block.id,
+    });
+  }
+}
+
 /** Truthiness of the `squisq-auto-templates` frontmatter kill-switch. */
 function frontmatterDisablesAutoTemplates(markdownDoc: MarkdownDocument): boolean {
   const v = markdownDoc.frontmatter?.['squisq-auto-templates'];
@@ -752,12 +873,25 @@ function applyAutoTemplates(
 
 /**
  * Extract the plain text from a block's body contents (excluding heading text).
+ *
+ * Exported because the narration script builder and the narration timing
+ * resolver must derive the *same* spoken text per block that captions and
+ * reading-time use — one source of truth for "what does this block say".
  */
-function getBlockBodyText(block: Block): string {
+export function getBlockBodyText(block: Block): string {
   if (!block.contents || block.contents.length === 0) return '';
+  // A fence consumed as diagram data must not feed reading-time/captions —
+  // 20 lines of box-drawing art would add ~30s of duration and captions
+  // that "read" border runs aloud.
+  const tmpl = resolveTemplateName(block.template ?? '');
+  const consumedFence =
+    (tmpl === 'diagram' && block.templateData !== undefined && 'nodes' in block.templateData) ||
+    (tmpl === 'timeline' && block.templateData !== undefined && 'tracks' in block.templateData) ||
+    (tmpl === 'tree' && block.templateData !== undefined && 'items' in block.templateData);
   // Join with newlines to preserve paragraph/list-item boundaries.
   // splitIntoPhrases uses these newlines as natural split points.
   return block.contents
+    .filter((node) => !(consumedFence && node.type === 'code'))
     .map((node) => extractPlainText(node))
     .join('\n')
     .trim();