@bendyline/squisq 1.4.0 → 1.5.0

package/src/doc/customTemplatesFrontmatter.ts

@@ -0,0 +1,308 @@
+/**
+ * Frontmatter serialization for user-defined custom templates (layouts).
+ *
+ * Custom template definitions live in the document's YAML frontmatter
+ * under the key `squisq-custom-templates`. They're stored as a single
+ * **compact JSON** object keyed by template name:
+ *
+ * ```yaml
+ * squisq-custom-templates: {"hero":{"lb":"Hero Section","ly":[{"ty":"text",…}]}}
+ * ```
+ *
+ * Squisq's frontmatter parser is line-based; a JSON object literal
+ * round-trips through it verbatim (no leading quote to strip, single
+ * line), so the value is written **unquoted** and stays human-readable
+ * and diffable — important for a codebase edited by people and agents.
+ *
+ * The JSON is kept small by:
+ *   - keying definitions by `name` (drops the `name` field + array wrapper),
+ *   - omitting the viewport when it's the 1920×1080 default,
+ *   - renaming well-known property names to two-letter codes via
+ *     {@link LONG_TO_SHORT} (e.g. `fontSize` → `fz`).
+ *
+ * The rename is a generic, recursive, bijective pass: **any property not
+ * in the map passes through unchanged**, so the format is lossless even
+ * as the Layer schema grows — new fields are simply stored under their
+ * full name until (optionally) added to the map.
+ *
+ * Back-compat: the reader still accepts the historical base64-of-JSON
+ * 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';
+import type { CustomTemplateDefinition } from '../schemas/CustomTemplates.js';
+import { FRONTMATTER_CUSTOM_TEMPLATES_KEY } from '../schemas/CustomTemplates.js';
+
+const DEFAULT_VIEWPORT = { width: 1920, height: 1080 };
+
+/** Re-export for callers that need the canonical key spelling. */
+export { FRONTMATTER_CUSTOM_TEMPLATES_KEY };
+
+// ─── Compact key codec ──────────────────────────────────────────────
+
+/**
+ * Long → short property-name map. Values must be unique and must not
+ * collide with any real key that passes through unmapped (those are
+ * 1-char — `x`/`y`/`d`/`id`/`to` — or full words; the codes here are
+ * 2-letter combos, so they never clash). A field literally named like a
+ * code (e.g. a real `fz` key) would be the one corruption case — none
+ * exist in the schema, and the round-trip test guards against it.
+ */
+const LONG_TO_SHORT: Readonly<Record<string, string>> = {
+  // definition
+  label: 'lb',
+  description: 'ds',
+  viewport: 'vp',
+  layers: 'ly',
+  name: 'nm',
+  // layer
+  type: 'ty',
+  position: 'po',
+  content: 'ct',
+  animation: 'am',
+  // position
+  width: 'wd',
+  height: 'hg',
+  anchor: 'an',
+  // text
+  text: 'tx',
+  style: 'sy',
+  fontSize: 'fz',
+  fontFamily: 'ff',
+  fontWeight: 'fw',
+  color: 'cl',
+  textAlign: 'al',
+  verticalAlign: 'vl',
+  lineHeight: 'lh',
+  shadow: 'sd',
+  background: 'bg',
+  backgroundOpacity: 'bo',
+  backgroundGradient: 'bj',
+  borderColor: 'bc',
+  borderWidth: 'bw',
+  borderStyle: 'bs',
+  padding: 'pd',
+  maxLines: 'mx',
+  // shape / path
+  shape: 'sp',
+  fill: 'fl',
+  fillOpacity: 'fo',
+  gradient: 'gr',
+  stroke: 'sk',
+  strokeWidth: 'sw',
+  borderRadius: 'br',
+  shapeKind: 'kd',
+  dasharray: 'da',
+  arrow: 'ar',
+  startMarker: 'st',
+  endMarker: 'em',
+  // image
+  src: 'sc',
+  alt: 'at',
+  fit: 'ft',
+  credit: 'cr',
+  license: 'lc',
+  // gradient
+  from: 'fr',
+  angle: 'ag',
+};
+
+const SHORT_TO_LONG: Readonly<Record<string, string>> = Object.fromEntries(
+  Object.entries(LONG_TO_SHORT).map(([long, short]) => [short, long]),
+);
+
+/** Recursively rename an object's keys via `map`, leaving unmapped keys. */
+function renameKeys(value: unknown, map: Readonly<Record<string, string>>): unknown {
+  if (Array.isArray(value)) return value.map((v) => renameKeys(v, map));
+  if (value && typeof value === 'object') {
+    const out: Record<string, unknown> = {};
+    for (const [k, v] of Object.entries(value as Record<string, unknown>)) {
+      out[map[k] ?? k] = renameKeys(v, map);
+    }
+    return out;
+  }
+  return value;
+}
+
+function isDefaultViewport(v: { width: number; height: number } | undefined): boolean {
+  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') {
+    const binary = globalThis.atob(b64);
+    const bytes = new Uint8Array(binary.length);
+    for (let i = 0; i < binary.length; i++) bytes[i] = binary.charCodeAt(i);
+    return new TextDecoder().decode(bytes);
+  }
+  return Buffer.from(b64, 'base64').toString('utf-8');
+}
+
+// ─── Definition list read / write ───────────────────────────────────
+
+/**
+ * Read the `squisq-custom-templates` frontmatter key and decode it into
+ * an array of CustomTemplateDefinitions. Returns undefined when the key
+ * is absent or unparseable so callers can omit the field from the Doc.
+ *
+ * Accepts, in order: the compact JSON object (current), a base64-JSON
+ * string (legacy), and an already-structured array/object (in case a
+ * richer YAML parser delivers it). Malformed payloads return undefined
+ * rather than failing the whole doc load.
+ */
+export function readCustomTemplatesFromFrontmatter(
+  frontmatter: Record<string, unknown> | undefined,
+): CustomTemplateDefinition[] | undefined {
+  if (!frontmatter) return undefined;
+  const candidates = normalizeCandidates(frontmatter[FRONTMATTER_CUSTOM_TEMPLATES_KEY]);
+  if (!candidates) return undefined;
+  const out: CustomTemplateDefinition[] = [];
+  for (const entry of candidates) {
+    if (!entry || typeof entry !== 'object') continue;
+    const e = entry as Record<string, unknown>;
+    if (typeof e.name !== 'string' || typeof e.label !== 'string') continue;
+    if (!Array.isArray(e.layers)) continue;
+    const def: CustomTemplateDefinition = {
+      name: e.name,
+      label: e.label,
+      viewport: readViewport(e.viewport),
+      layers: e.layers as Layer[],
+    };
+    if (typeof e.description === 'string') def.description = e.description;
+    out.push(def);
+  }
+  return out.length > 0 ? out : undefined;
+}
+
+/**
+ * Encode a list of custom template definitions into the compact JSON
+ * object described in the module header. Returns undefined when the
+ * input list is empty so callers can leave the key off the output.
+ */
+export function writeCustomTemplatesToFrontmatter(
+  templates: readonly CustomTemplateDefinition[] | undefined,
+): string | undefined {
+  if (!templates || templates.length === 0) return undefined;
+  const map: Record<string, Record<string, unknown>> = {};
+  for (const def of templates) {
+    const entry: Record<string, unknown> = { lb: def.label };
+    if (def.description) entry.ds = def.description;
+    if (!isDefaultViewport(def.viewport)) entry.vp = def.viewport;
+    entry.ly = renameKeys(def.layers, LONG_TO_SHORT);
+    map[def.name] = entry;
+  }
+  return JSON.stringify(map);
+}
+
+function readViewport(raw: unknown): { width: number; height: number } {
+  if (raw && typeof raw === 'object') {
+    const v = raw as Record<string, unknown>;
+    const w = typeof v.width === 'number' ? v.width : DEFAULT_VIEWPORT.width;
+    const h = typeof v.height === 'number' ? v.height : DEFAULT_VIEWPORT.height;
+    return { width: w, height: h };
+  }
+  return DEFAULT_VIEWPORT;
+}
+
+/**
+ * Expand the compact, name-keyed map into full-keyed definition objects
+ * that {@link readCustomTemplatesFromFrontmatter}'s validation loop
+ * understands. The `name` comes from the map key.
+ */
+function expandCompactMap(map: Record<string, unknown>): unknown[] {
+  return Object.entries(map).map(([name, raw]) => {
+    const e = (raw && typeof raw === 'object' ? raw : {}) as Record<string, unknown>;
+    const def: Record<string, unknown> = {
+      name,
+      label: e.lb,
+      viewport: e.vp ?? { ...DEFAULT_VIEWPORT },
+      layers: renameKeys(e.ly ?? [], SHORT_TO_LONG),
+    };
+    if (typeof e.ds === 'string') def.description = e.ds;
+    return def;
+  });
+}
+
+/** Turn a parsed value into a list of full-keyed definition objects. */
+function fromParsed(parsed: unknown): unknown[] | null {
+  if (Array.isArray(parsed)) return parsed; // legacy structured array
+  if (parsed && typeof parsed === 'object')
+    return expandCompactMap(parsed as Record<string, unknown>);
+  return null;
+}
+
+function tryJson(s: string): unknown | undefined {
+  try {
+    return JSON.parse(s);
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * Normalize any supported payload shape into a list of full-keyed
+ * definition objects. Returns null when the value is none of them.
+ */
+function normalizeCandidates(raw: unknown): unknown[] | null {
+  if (raw == null) return null;
+  if (Array.isArray(raw)) return raw;
+  if (typeof raw === 'object') return expandCompactMap(raw as Record<string, unknown>);
+  if (typeof raw !== 'string') return null;
+
+  // Current format: a JSON object/array literal stored verbatim.
+  const direct = tryJson(raw.trim());
+  if (direct !== undefined) return fromParsed(direct);
+
+  // Legacy format: base64-encoded JSON.
+  try {
+    const decoded = tryJson(base64ToUtf8(raw));
+    if (decoded !== undefined) return fromParsed(decoded);
+  } catch {
+    // not valid base64 either
+  }
+  return null;
+}

package/src/doc/customThemesFrontmatter.ts

@@ -0,0 +1,90 @@
+/**
+ * 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,
+): string | undefined {
+  if (!themes || themes.length === 0) return undefined;
+  const map: Record<string, Theme> = {};
+  for (const theme of themes) map[theme.id] = theme;
+  return JSON.stringify(map);
+}

package/src/doc/docToMarkdown.ts

@@ -24,6 +24,14 @@
 
 import type { Doc, Block } from '../schemas/Doc.js';
 import type { MarkdownDocument, MarkdownBlockNode, MarkdownHeading } from '../markdown/types.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.
@@ -66,9 +74,36 @@ 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 } : {}),
   };
 }
 
@@ -77,22 +112,56 @@ export function docToMarkdown(doc: Doc): MarkdownDocument {
  * 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;
+
+  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,9 @@ 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 { expandPersistentLayers, wrapWithPersistentLayers } from './templates/persistentLayers.js';
+import { applyRenderStyleToLayers } from './utils/applyRenderStyle.js';
+import { fallbackBlockLayers } from './templates/fallbackBlock.js';
 
 // ============================================
 // RenderContext
@@ -109,9 +111,22 @@ 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.
+      const { templateData, templateOverrides } = block as Block;
+      const input =
+        templateData || templateOverrides
+          ? ({ ...block, ...templateData, ...templateOverrides } as TemplateBlock)
+          : block;
       let layers: Layer[];
       try {
         // Each registry entry accepts its specific TemplateBlock variant; the
@@ -120,21 +135,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 +178,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,43 @@
 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,
+  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';