@bendyline/squisq 1.4.1 → 1.5.1

package/src/doc/customThemesFrontmatter.ts

@@ -0,0 +1,95 @@
+/**
+ * Frontmatter serialization for user-defined custom themes.
+ *
+ * The theme analog of {@link ./customTemplatesFrontmatter.ts}. Custom Theme
+ * definitions live in the document's YAML frontmatter under the key
+ * `squisq-custom-themes`, stored as a single **compact JSON** object keyed
+ * by theme id:
+ *
+ * ```yaml
+ * squisq-custom-themes: {"my-brand":{"schemaVersion":"1","id":"my-brand",…}}
+ * ```
+ *
+ * Squisq's frontmatter parser is line-based; a JSON object literal
+ * round-trips through it verbatim (single line, no leading quote to strip),
+ * so the value is written **unquoted** and stays human-readable and diffable
+ * — the same mechanism the custom-templates codec relies on.
+ *
+ * Only one theme is *active* per doc (selected by id via the `squisq-theme`
+ * frontmatter key / `Doc.themeId`), but the payload is a keyed map — parallel
+ * to custom templates — so a doc can carry a small catalog and switch between
+ * them, and `resolveThemeForDoc` can resolve any of them doc-scoped.
+ *
+ * Malformed entries are dropped (via `validateTheme`) rather than failing the
+ * whole doc load, matching the tolerant behavior of the templates reader.
+ */
+
+import type { Theme } from '../schemas/Theme.js';
+import { FRONTMATTER_CUSTOM_THEMES_KEY } from '../schemas/Theme.js';
+import { validateTheme } from '../schemas/themeValidator.js';
+
+/** Re-export for callers that need the canonical key spelling. */
+export { FRONTMATTER_CUSTOM_THEMES_KEY };
+
+/**
+ * Normalize the raw frontmatter value into an array of candidate objects.
+ * Accepts, in order: a JSON string (current, from the line-based parser),
+ * an already-parsed object map (keyed by id), and an array (in case a richer
+ * YAML parser delivers one). Returns undefined when absent/unparseable.
+ */
+function normalizeCandidates(raw: unknown): unknown[] | undefined {
+  if (raw === undefined || raw === null) return undefined;
+  let value: unknown = raw;
+  if (typeof value === 'string') {
+    const trimmed = value.trim();
+    if (!trimmed) return undefined;
+    try {
+      value = JSON.parse(trimmed);
+    } catch {
+      return undefined;
+    }
+  }
+  if (Array.isArray(value)) return value;
+  if (value && typeof value === 'object') {
+    return Object.values(value as Record<string, unknown>);
+  }
+  return undefined;
+}
+
+/**
+ * Read the custom themes inlined into a document's frontmatter. Returns
+ * undefined when the key is absent or holds no valid theme, so callers can
+ * omit the field from the Doc.
+ */
+export function readCustomThemesFromFrontmatter(
+  frontmatter: Record<string, unknown> | undefined,
+): Theme[] | undefined {
+  if (!frontmatter) return undefined;
+  const candidates = normalizeCandidates(frontmatter[FRONTMATTER_CUSTOM_THEMES_KEY]);
+  if (!candidates) return undefined;
+  const out: Theme[] = [];
+  for (const entry of candidates) {
+    const result = validateTheme(entry);
+    if (result.valid && result.theme) out.push(result.theme);
+  }
+  return out.length > 0 ? out : undefined;
+}
+
+/**
+ * Encode a list of custom themes into the compact JSON object described in
+ * the module header (keyed by theme id). Returns undefined when the input is
+ * empty so callers can leave the key off the output.
+ */
+export function writeCustomThemesToFrontmatter(
+  themes: readonly Theme[] | undefined,
+  options?: { pretty?: boolean },
+): string | undefined {
+  if (!themes || themes.length === 0) return undefined;
+  const map: Record<string, Theme> = {};
+  for (const theme of themes) map[theme.id] = theme;
+  // Pretty output is multi-line, so it serializes as a YAML literal block
+  // scalar (see the markdown stringify frontmatter path) and reads back via
+  // `JSON.parse`. Default stays compact (single line) so existing docs and
+  // snapshots are byte-unchanged.
+  return JSON.stringify(map, null, options?.pretty ? 2 : undefined);
+}

package/src/doc/docToMarkdown.ts

@@ -23,7 +23,21 @@
  */
 
 import type { Doc, Block } from '../schemas/Doc.js';
-import type { MarkdownDocument, MarkdownBlockNode, MarkdownHeading } from '../markdown/types.js';
+import type {
+  MarkdownDocument,
+  MarkdownBlockNode,
+  MarkdownHeading,
+  MarkdownParagraph,
+} from '../markdown/types.js';
+import { serializeAnnotation } from '../markdown/attrTokens.js';
+import {
+  FRONTMATTER_CUSTOM_TEMPLATES_KEY,
+  writeCustomTemplatesToFrontmatter,
+} from './customTemplatesFrontmatter.js';
+import {
+  FRONTMATTER_CUSTOM_THEMES_KEY,
+  writeCustomThemesToFrontmatter,
+} from './customThemesFrontmatter.js';
 
 /**
  * Convert a Doc with heading-driven blocks back to a MarkdownDocument.
@@ -47,6 +61,12 @@ export function docToMarkdown(doc: Doc): MarkdownDocument {
     if (block.sourceHeading) {
       const heading = ensureAnnotation(block, block.sourceHeading);
       children.push(heading);
+    } else if (block.standaloneAnnotation) {
+      // Heading-less standalone block: re-emit its `{[…]}` annotation as a
+      // paragraph before its contents. The serializer's quoting is paired
+      // with the tokenizer, and stringifyMarkdown un-escapes `{[…]}` spans,
+      // so the annotation round-trips.
+      children.push(synthesizeAnnotationParagraph(block));
     }
 
     // Emit body content
@@ -66,33 +86,112 @@ export function docToMarkdown(doc: Doc): MarkdownDocument {
     emitBlock(block);
   }
 
+  // Merge `Doc.customTemplates` into the outgoing frontmatter so the
+  // markdown remains the source-of-truth: edits made via the editor's
+  // TemplateDesigner round-trip through `docToMarkdown` →
+  // `stringifyMarkdown` and are visible to anyone reading the file.
+  const customPayload = writeCustomTemplatesToFrontmatter(doc.customTemplates);
+  let frontmatter = doc.frontmatter;
+  if (customPayload) {
+    frontmatter = { ...(frontmatter ?? {}), [FRONTMATTER_CUSTOM_TEMPLATES_KEY]: customPayload };
+  } else if (frontmatter && FRONTMATTER_CUSTOM_TEMPLATES_KEY in frontmatter) {
+    // The doc has no custom templates anymore — drop the stale
+    // frontmatter key so the markdown reflects the current state.
+    const { [FRONTMATTER_CUSTOM_TEMPLATES_KEY]: _drop, ...rest } = frontmatter;
+    void _drop;
+    frontmatter = rest;
+  }
+
+  // Mirror the same round-trip for `Doc.customThemes` (the theme analog).
+  const customThemesPayload = writeCustomThemesToFrontmatter(doc.customThemes);
+  if (customThemesPayload) {
+    frontmatter = { ...(frontmatter ?? {}), [FRONTMATTER_CUSTOM_THEMES_KEY]: customThemesPayload };
+  } else if (frontmatter && FRONTMATTER_CUSTOM_THEMES_KEY in frontmatter) {
+    const { [FRONTMATTER_CUSTOM_THEMES_KEY]: _dropTheme, ...rest } = frontmatter;
+    void _dropTheme;
+    frontmatter = rest;
+  }
+
   return {
     type: 'document',
     children,
+    ...(frontmatter && Object.keys(frontmatter).length > 0 ? { frontmatter } : {}),
   };
 }
 
+/**
+ * Build the synthesized annotation paragraph for a heading-less standalone
+ * block: `{[templateName key=value …]}` from its `sourceAnnotation.template`
+ * and current `templateOverrides` (edits round-trip through the latter).
+ */
+function synthesizeAnnotationParagraph(block: Block): MarkdownParagraph {
+  const text = serializeAnnotation(block.sourceAnnotation?.template, block.templateOverrides);
+  return { type: 'paragraph', children: [{ type: 'text', value: text }] };
+}
+
 /**
  * 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;
+  const attrs = ensureTransitionAttributes(block, heading);
 
   // If the block has a non-default template or overrides, inject an annotation
-  const hasExplicitTemplate = block.template && block.template !== 'sectionHeader';
+  const hasExplicitTemplate =
+    block.template && block.template !== 'sectionHeader' && block.autoTemplate !== true;
   const hasOverrides = block.templateOverrides && Object.keys(block.templateOverrides).length > 0;
 
-  if (!hasExplicitTemplate && !hasOverrides) return heading;
+  // If the heading already has an annotation, trust it (it came from parsing).
+  // Transition attrs may still have been injected above if the block changed.
+  if (heading.templateAnnotation) {
+    return attrs === heading.attributes ? heading : { ...heading, attributes: attrs };
+  }
+
+  if (!hasExplicitTemplate && !hasOverrides) {
+    return attrs === heading.attributes ? heading : { ...heading, attributes: attrs };
+  }
 
   // Clone to avoid mutating the original
   return {
     ...heading,
     children: [...heading.children],
+    attributes: attrs,
     templateAnnotation: {
       template: block.template ?? 'sectionHeader',
       ...(hasOverrides ? { params: block.templateOverrides } : {}),
     },
   };
 }
+
+function ensureTransitionAttributes(
+  block: Block,
+  heading: MarkdownHeading,
+): MarkdownHeading['attributes'] {
+  const transition = block.transition;
+  if (!transition) return heading.attributes;
+
+  // The transition is deliberately written to BOTH channels, which serve
+  // different consumers:
+  // - `params` is what `stringifyMarkdown` serializes into the Pandoc `{…}`
+  //   attribute text (serializePandocAttributes reads only id/classes/params).
+  // - `blockMeta` is what `markdownToDoc` reads back directly (makeBlock,
+  //   pinnedHeadingMeta) — an in-memory Doc → MarkdownDocument → Doc round
+  //   trip never re-parses params, so a stale/missing `blockMeta.transition`
+  //   would lose or resurrect the wrong transition.
+  const attrs = heading.attributes ?? {};
+  return {
+    ...attrs,
+    params: {
+      ...(attrs.params ?? {}),
+      transition: transition.type,
+      ...(transition.duration !== undefined
+        ? { transitionDuration: String(transition.duration) }
+        : {}),
+      ...(transition.direction ? { transitionDirection: transition.direction } : {}),
+    },
+    blockMeta: {
+      ...(attrs.blockMeta ?? {}),
+      transition,
+    },
+  };
+}

package/src/doc/getLayers.ts

@@ -35,7 +35,10 @@ import { VIEWPORT_PRESETS } from '../schemas/Viewport.js';
 import { createTemplateContext, isTemplateBlock } from '../schemas/BlockTemplates.js';
 import { DEFAULT_THEME } from '../schemas/themeLibrary.js';
 import { templateRegistry, resolveTemplateName } from './templates/index.js';
-import { expandPersistentLayers } from './templates/persistentLayers.js';
+import { coerceTemplateParams } from './templates/inputDescriptors.js';
+import { expandPersistentLayers, wrapWithPersistentLayers } from './templates/persistentLayers.js';
+import { applyRenderStyleToLayers } from './utils/applyRenderStyle.js';
+import { fallbackBlockLayers } from './templates/fallbackBlock.js';
 
 // ============================================
 // RenderContext
@@ -109,9 +112,30 @@ export function getLayers(block: DocBlock, context: RenderContext = {}): Layer[]
   // and the layer list comes back empty.
   if (isTemplateBlock(block)) {
     const resolved = resolveTemplateName(block.template);
+    const templateCtx = createTemplateContext(theme, blockIndex, totalBlocks, viewport);
     if (resolved in templateRegistry) {
       const templateName = resolved as keyof typeof templateRegistry;
-      const templateCtx = createTemplateContext(theme, blockIndex, totalBlocks, viewport);
+      // Aggregate templates (e.g. `diagram`) consume the block's children.
+      const maybeChildren = (block as Block).children;
+      if (maybeChildren && maybeChildren.length > 0) {
+        templateCtx.children = maybeChildren;
+      }
+      // Effective template input: the block's own fields, then structured
+      // body data (```json data fences, GFM tables), then `{[…]}` string
+      // overrides — the same merge order buildPreviewDoc uses. Inline overrides
+      // are coerced to their typed shape (`center="47.6,-122.3"` → `{lat,lng}`,
+      // `zoom=9` → `9`) so pure-inline annotations render without any change to
+      // the template functions. `block.templateOverrides` itself stays raw
+      // strings for lossless round-tripping — only this ephemeral input is coerced.
+      const { templateData, templateOverrides } = block as Block;
+      const input =
+        templateData || templateOverrides
+          ? ({
+              ...block,
+              ...templateData,
+              ...coerceTemplateParams(block.template, templateOverrides ?? {}).input,
+            } as TemplateBlock)
+          : block;
       let layers: Layer[];
       try {
         // Each registry entry accepts its specific TemplateBlock variant; the
@@ -120,21 +144,34 @@ export function getLayers(block: DocBlock, context: RenderContext = {}): Layer[]
           input: TemplateBlock,
           ctx: TemplateContext,
         ) => Layer[];
-        layers = templateFn(block, templateCtx);
+        layers = templateFn(input, templateCtx);
         if (!Array.isArray(layers)) {
-          console.error(`Template ${templateName} did not return an array, got:`, typeof layers);
-          layers = [];
+          console.warn(`Template ${templateName} did not return an array, got:`, typeof layers);
+          layers = fallbackBlockLayers(block, templateCtx, `Template "${block.template}" failed`);
         }
       } catch (err: unknown) {
-        console.error(`Error expanding template ${templateName}:`, err);
-        layers = [];
+        console.warn(`Error expanding template ${templateName}:`, err);
+        layers = fallbackBlockLayers(block, templateCtx, `Template "${block.template}" failed`);
       }
 
+      // Theme motion defaults apply to template-generated layers only
+      // (mirrors expandDocBlocks — the two paths must agree).
+      layers = applyRenderStyleToLayers(layers, block as Block, theme);
+
       return injectPersistentLayers(layers, block, context);
     }
+
+    // Unknown template — graceful-degradation guarantee: render the
+    // block's heading + body text as a plain card with a visible notice
+    // instead of a blank slide.
+    return injectPersistentLayers(
+      fallbackBlockLayers(block, templateCtx, `Unknown template "${block.template}"`),
+      block,
+      context,
+    );
   }
 
-  // 3. Fallback: no layers and no known template
+  // 3. Fallback: no layers and no template requested
   return injectPersistentLayers([], block, context);
 }
 
@@ -150,14 +187,9 @@ function injectPersistentLayers(layers: Layer[], block: DocBlock, context: Rende
   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;
+  const theme = context.theme ?? DEFAULT_THEME;
+  const bottomLayers = expandPersistentLayers(persistentLayers.bottomLayers, theme);
+  const topLayers = expandPersistentLayers(persistentLayers.topLayers, theme);
 
-  return [...(useBottom ? bottomLayers : []), ...layers, ...(useTop ? topLayers : [])];
+  return wrapWithPersistentLayers(layers, block as TemplateBlock, bottomLayers, topLayers);
 }

package/src/doc/index.ts

@@ -1,9 +1,55 @@
 export * from './templates/index.js';
 export * from './utils/animationUtils.js';
 export * from './utils/themeUtils.js';
-export { markdownToDoc, flattenBlocks, countBlocks, getBlockDepth } from './markdownToDoc.js';
+export * from './utils/applyRenderStyle.js';
+export * from './utils/imageTreatment.js';
+export * from './templateInputs.js';
+export * from './utils/shapeGeometry.js';
+export {
+  markdownToDoc,
+  flattenBlocks,
+  flattenRenderableBlocks,
+  countBlocks,
+  getBlockDepth,
+} from './markdownToDoc.js';
 export type { MarkdownToDocOptions } from './markdownToDoc.js';
 export { docToMarkdown } from './docToMarkdown.js';
+export {
+  encodeLayersForFrontmatter,
+  decodeLayersFromFrontmatter,
+  readCustomTemplatesFromFrontmatter,
+  writeCustomTemplatesToFrontmatter,
+  FRONTMATTER_CUSTOM_TEMPLATES_KEY,
+} from './customTemplatesFrontmatter.js';
+export {
+  readCustomThemesFromFrontmatter,
+  writeCustomThemesToFrontmatter,
+  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 {
+  isDataFence,
+  parseDataFence,
+  replaceDataFence,
+  parseYamlSubset,
+  findFirstTable,
+  extractTableData,
+} from './structuredData.js';
+export type { DataFenceParseResult, ExtractedTableData } from './structuredData.js';
+export { validateMarkdownSource, validateMarkdownDoc } from './validate.js';
+export type { ValidateOptions, MarkdownValidationResult } from './validate.js';
+export { fallbackBlockLayers } from './templates/fallbackBlock.js';
+export {
+  BASE_INPUT_DESCRIPTORS,
+  TEMPLATE_INPUT_DESCRIPTORS,
+  coerceTemplateParams,
+  lintTemplateParams,
+} from './templates/inputDescriptors.js';
+export type {
+  InputCoercion,
+  TemplateInputDescriptor,
+  TemplateParamFinding,
+} from './templates/inputDescriptors.js';