@bendyline/squisq 1.4.1 → 1.5.1

package/src/__tests__/validateDoc.test.ts

@@ -0,0 +1,260 @@
+import { describe, it, expect } from 'vitest';
+import { validateMarkdownSource } from '../doc/validate.js';
+import { writeCustomTemplatesToFrontmatter } from '../doc/customTemplatesFrontmatter';
+import type { CustomTemplateDefinition } from '../schemas/CustomTemplates.js';
+
+function codes(md: string, options?: Parameters<typeof validateMarkdownSource>[1]): string[] {
+  return validateMarkdownSource(md, options).diagnostics.map((d) => d.code);
+}
+
+describe('validateMarkdownSource — templates', () => {
+  it('passes a clean document', () => {
+    const result = validateMarkdownSource('# Title\n\nBody.\n\n## Section {[quote]}\n\nA quote.\n');
+    expect(result.diagnostics).toEqual([]);
+    expect(result.errorCount).toBe(0);
+    expect(result.warningCount).toBe(0);
+    expect(result.infoCount).toBe(0);
+  });
+
+  it('flags unknown templates with a did-you-mean suggestion', () => {
+    const result = validateMarkdownSource('## Gallery {[photGrid columns=3]}');
+    expect(result.warningCount).toBe(1);
+    const d = result.diagnostics[0];
+    expect(d.code).toBe('unknown-template');
+    expect(d.message).toContain('photGrid');
+    expect(d.message).toContain('Did you mean "photoGrid"?');
+    expect(d.line).toBe(1);
+  });
+
+  it('accepts legacy template aliases', () => {
+    expect(codes('## X {[titleBlock]}')).toEqual([]);
+  });
+
+  it('accepts extra templates supplied by the host app', () => {
+    expect(codes('## X {[hero]}', { extraTemplates: ['hero'] })).toEqual([]);
+    expect(codes('## X {[hero]}')).toEqual(['unknown-template']);
+  });
+});
+
+describe('validateMarkdownSource — unparsed annotations', () => {
+  it('flags {[…]} text in body content (annotations are heading-only)', () => {
+    const result = validateMarkdownSource('## X\n\n- {[imageWithCaption src=photo.jpg]}\n');
+    const d = result.diagnostics.find((x) => x.code === 'unparsed-annotation');
+    expect(d).toBeDefined();
+    expect(d!.message).toContain('headings');
+    expect(d!.line).toBe(3);
+  });
+
+  it('flags non-trailing {[…]} text left in a heading', () => {
+    const result = validateMarkdownSource('## The {[chart]} section\n');
+    expect(result.diagnostics.map((d) => d.code)).toContain('unparsed-annotation');
+  });
+
+  it('does not flag resolved inline icons or code blocks', () => {
+    const md = '## X\n\nUse {[github]} for code.\n\n```\nliteral {[notathing]}\n```\n';
+    expect(codes(md)).toEqual([]);
+  });
+});
+
+describe('validateMarkdownSource — attributes and structure', () => {
+  it('surfaces malformed heading-attribute values', () => {
+    const result = validateMarkdownSource('## X {#a x=abc}');
+    const d = result.diagnostics.find((x) => x.code === 'invalid-attribute');
+    expect(d).toBeDefined();
+    expect(d!.message).toContain('x');
+  });
+
+  it('includes conversion diagnostics (duplicate ids, bad fences)', () => {
+    const md = '## A {#dup}\n\n## B {#dup}\n\n```json data\nnot json\n```\n';
+    const result = validateMarkdownSource(md);
+    const found = result.diagnostics.map((d) => d.code);
+    expect(found).toContain('duplicate-id');
+    expect(found).toContain('data-fence-parse');
+    expect(result.errorCount).toBe(2);
+  });
+});
+
+describe('validateMarkdownSource — conflicting annotation keys', () => {
+  it('flags a block-meta key set differently in both {[…]} and {…}', () => {
+    const result = validateMarkdownSource('## X {[sectionHeader duration=8]} {#x duration=10}\n');
+    const d = result.diagnostics.find((x) => x.code === 'conflicting-annotation-key');
+    expect(d).toBeDefined();
+    expect(d!.severity).toBe('info');
+    expect(d!.message).toBe(
+      '"duration" is set in both {[…]} (8) and {…} (10) — the {…} value wins.',
+    );
+    expect(d!.blockId).toBe('x');
+    expect(d!.line).toBe(1);
+    expect(result.infoCount).toBe(1);
+    expect(result.errorCount).toBe(0);
+    expect(result.warningCount).toBe(0);
+    // Precedence itself is unchanged: the Pandoc value is in effect.
+    expect(result.doc.blocks[0].duration).toBe(10);
+  });
+
+  it('stays silent when both forms agree', () => {
+    expect(codes('## X {[sectionHeader duration=8]} {#x duration=8}\n')).toEqual([]);
+  });
+
+  it('ignores non-block-meta keys (they land in different channels)', () => {
+    // `style` goes to templateOverrides ({[…]}) and metadata ({…}) — no conflict.
+    expect(codes('## X {[factCard style=minimal]} {#x style=bold}\n')).toEqual([]);
+  });
+
+  it('reports each conflicting key separately', () => {
+    const result = validateMarkdownSource(
+      '## X {[sectionHeader duration=8 startTime=1]} {#x duration=10 startTime=2}\n',
+    );
+    const found = result.diagnostics.filter((d) => d.code === 'conflicting-annotation-key');
+    expect(found).toHaveLength(2);
+    expect(result.infoCount).toBe(2);
+  });
+});
+
+describe('validateMarkdownSource — assets', () => {
+  it('flags relative image references missing from the asset set', () => {
+    const result = validateMarkdownSource('## X\n\n![hero](images/hero.jpg)\n', {
+      assets: new Set<string>(),
+    });
+    const d = result.diagnostics.find((x) => x.code === 'missing-asset');
+    expect(d).toBeDefined();
+    expect(d!.message).toContain('images/hero.jpg');
+  });
+
+  it('passes when the asset exists, and skips absolute/external URLs', () => {
+    const md =
+      '## X\n\n![a](images/hero.jpg)\n\n![b](https://example.com/x.jpg)\n\n![c](data:image/png;base64,AA==)\n';
+    expect(codes(md, { assets: new Set(['images/hero.jpg']) })).toEqual([]);
+  });
+
+  it('checks media params from {[…]} annotations', () => {
+    const result = validateMarkdownSource('## X {[imageWithCaption src=missing.png]}', {
+      assets: new Set<string>(),
+    });
+    expect(result.diagnostics.map((d) => d.code)).toContain('missing-asset');
+  });
+
+  it('skips asset checks entirely when no asset set is provided', () => {
+    expect(codes('## X\n\n![hero](images/hero.jpg)\n')).toEqual([]);
+  });
+});
+
+describe('validateMarkdownSource — template inputs', () => {
+  it('flags an unknown input with a did-you-mean suggestion', () => {
+    const result = validateMarkdownSource('## Where {[map centre="47.6,-122.3"]}');
+    const d = result.diagnostics.find((x) => x.code === 'unknown-input');
+    expect(d).toBeDefined();
+    expect(d!.severity).toBe('warning');
+    expect(d!.message).toContain('centre');
+    expect(d!.message).toContain('Did you mean "center"?');
+    expect(d!.line).toBe(1);
+  });
+
+  it('flags a value outside a closed enum', () => {
+    const result = validateMarkdownSource('## Where {[map center="1,2" mapStyle="nope"]}');
+    const d = result.diagnostics.find((x) => x.code === 'invalid-input-value');
+    expect(d).toBeDefined();
+    expect(d!.message).toContain('mapStyle');
+    expect(d!.message).toContain('terrain');
+  });
+
+  it('flags a missing required input', () => {
+    const codesFor = codes('## Compare {[twoColumn]}');
+    expect(codesFor.filter((c) => c === 'missing-input')).toEqual([
+      'missing-input',
+      'missing-input',
+    ]);
+  });
+
+  it('does not fire missing-input when the value is derivable from the body', () => {
+    const md = '## Caption {[imageWithCaption]}\n\n![a beach](beach.jpg)\n';
+    // imageSrc is required, but derivable from the body image → no warning.
+    expect(codes(md)).not.toContain('missing-input');
+  });
+
+  it('does fire missing-input when the value is not derivable and absent', () => {
+    // No body image → imageSrc is neither present nor derivable.
+    expect(codes('## Caption {[imageWithCaption]}')).toContain('missing-input');
+  });
+
+  it('does not lint blocks that resolve to a doc-declared custom template', () => {
+    // A custom template that shadows the built-in "map" name carries its own
+    // arbitrary inputs — the built-in descriptors must not be applied to it.
+    const custom: CustomTemplateDefinition = {
+      name: 'map',
+      label: 'My Map',
+      description: 'custom',
+      viewport: { width: 1920, height: 1080 },
+      layers: [
+        {
+          id: 't',
+          type: 'text',
+          position: { x: '5%', y: '10%' },
+          content: { text: '{title}', style: { fontSize: 40, color: '#000' } },
+        },
+      ],
+    };
+    const encoded = writeCustomTemplatesToFrontmatter([custom])!;
+    const md = `---\nsquisq-custom-templates: ${encoded}\n---\n\n## Hi {[map foo="bar"]}\n`;
+    const codesFor = validateMarkdownSource(md).diagnostics.map((d) => d.code);
+    expect(codesFor).not.toContain('unknown-input');
+    expect(codesFor).not.toContain('missing-input');
+  });
+
+  it('does not lint templates without descriptors', () => {
+    // sectionHeader has no input descriptors → arbitrary keys are not flagged.
+    expect(codes('## Break {[sectionHeader whatever=5]}')).toEqual([]);
+  });
+
+  it('leaves a clean, fully-specified block with no findings', () => {
+    const md = '## Where {[map center="47.6,-122.3" zoom=9 mapStyle="terrain"]}';
+    expect(codes(md)).toEqual([]);
+  });
+});
+
+describe('validateMarkdownSource — standalone annotations (S2)', () => {
+  it('does not flag a valid standalone template annotation as unparsed', () => {
+    const result = validateMarkdownSource('# H\n\n{[quote]}\n\nquoted\n');
+    expect(result.diagnostics.find((d) => d.code === 'unparsed-annotation')).toBeUndefined();
+    expect(result.diagnostics.find((d) => d.code === 'unknown-template')).toBeUndefined();
+  });
+
+  it('reports unknown-template for a standalone annotation with a bad name', () => {
+    const result = validateMarkdownSource('# H\n\n{[quotte]}\n\nquoted\n');
+    const d = result.diagnostics.find((x) => x.code === 'unknown-template');
+    expect(d).toBeDefined();
+    expect(d!.message).toContain('quotte');
+    // Not double-reported as an unparsed annotation.
+    expect(result.diagnostics.find((x) => x.code === 'unparsed-annotation')).toBeUndefined();
+  });
+
+  it('still flags {[…]} nested inside a list (not a standalone block)', () => {
+    const result = validateMarkdownSource('## X\n\n- {[imageWithCaption src=x.jpg]}\n');
+    const d = result.diagnostics.find((x) => x.code === 'unparsed-annotation');
+    expect(d).toBeDefined();
+    expect(d!.message).toContain('standalone paragraphs');
+  });
+});
+
+describe('validateMarkdownSource — possible-data-fence (S3)', () => {
+  const info = (md: string) =>
+    validateMarkdownSource(md).diagnostics.filter((d) => d.code === 'possible-data-fence');
+
+  it('nudges an unmarked json fence inside a template-annotated block', () => {
+    const md = '## Numbers {[dataTable]}\n\n```json\n{ "headers": ["A"], "rows": [] }\n```\n';
+    const d = info(md);
+    expect(d).toHaveLength(1);
+    expect(d[0].severity).toBe('info');
+    expect(d[0].message).toContain('```json data');
+  });
+
+  it('does not fire for a code sample in a non-templated prose section', () => {
+    const md = '## Notes\n\n```json\n{ "a": 1 }\n```\n';
+    expect(info(md)).toHaveLength(0);
+  });
+
+  it('does not fire when the fence already has the data marker', () => {
+    const md = '## Numbers {[dataTable]}\n\n```json data\n{ "headers": ["A"], "rows": [] }\n```\n';
+    expect(info(md)).toHaveLength(0);
+  });
+});

package/src/doc/annotationBlocks.ts

@@ -0,0 +1,117 @@
+/**
+ * Standalone template-annotation block extraction.
+ *
+ * A paragraph whose entire trimmed text is exactly `{[templateName key=value …]}`
+ * — where `templateName` is not a media name (media annotations are extracted
+ * first, into typed clips) — becomes a *heading-less template block*. The body
+ * nodes that follow it, up to the next heading or the next standalone
+ * annotation, become that block's `contents`.
+ *
+ * This is the block analog of {@link import('./mediaAnnotations.js').extractMediaFromContents}:
+ * both walk a block's body `contents` and lift standalone `{[…]}` paragraphs
+ * out, sharing the {@link parseStandaloneAnnotation} parser. Runs AFTER media
+ * extraction (so media names keep their meaning) and BEFORE structured-data
+ * parsing (so `json data` / `yaml data` fences attach to the new blocks).
+ */
+
+import type { Block } from '../schemas/Doc.js';
+import type { MarkdownBlockNode } from '../markdown/types.js';
+import { coerceAnnotationValues, type CoercedBlockMeta } from '../markdown/annotationCoercion.js';
+import { resolveTemplateName } from './templates/index.js';
+import { isMediaAnnotationName } from './mediaAnnotations.js';
+import { parseStandaloneAnnotation, type ParsedAnnotation } from './standaloneAnnotation.js';
+
+/** Configuration for {@link extractTemplateBlocksFromContents}. */
+export interface StandaloneBlockOptions {
+  /** Produce a unique block id for a parsed standalone annotation. */
+  makeId: (parsed: ParsedAnnotation) => string;
+  /** Initial `duration` for a produced block (the timing pass overrides it). */
+  defaultDuration: number;
+}
+
+/** The split produced by {@link extractTemplateBlocksFromContents}. */
+export interface TemplateBlockExtraction {
+  /** Contents before the first standalone template annotation (stay on the
+   *  containing block). */
+  leading: MarkdownBlockNode[];
+  /** Heading-less blocks, each carrying the body nodes that followed its
+   *  annotation up to the next annotation / end of contents. */
+  blocks: Block[];
+}
+
+/**
+ * Apply coerced block-meta values onto a produced block. Mirrors
+ * `markdownToDoc`'s `applyBlockMeta` so a standalone `{[quote duration=8]}`
+ * honors the same block-meta keys a heading `{[…]}` annotation would.
+ */
+function applyBlockMeta(block: Block, m: CoercedBlockMeta): void {
+  if (m.x != null) block.x = m.x;
+  if (m.y != null) block.y = m.y;
+  if (m.startTime != null) block.startTime = m.startTime;
+  if (m.duration != null) block.duration = m.duration;
+  if (m.connectsTo) block.connectsTo = m.connectsTo;
+  if (m.transition) block.transition = m.transition;
+}
+
+/** Build a heading-less block from a parsed standalone template annotation. */
+function makeStandaloneBlock(parsed: ParsedAnnotation, options: StandaloneBlockOptions): Block {
+  // `parsed.template` is guaranteed defined by the caller's guard.
+  const rawTemplate = parsed.template as string;
+  const params = parsed.params;
+  const hasParams = Object.keys(params).length > 0;
+
+  const block: Block = {
+    id: options.makeId(parsed),
+    startTime: 0,
+    duration: options.defaultDuration,
+    audioSegment: 0,
+    template: resolveTemplateName(rawTemplate),
+    standaloneAnnotation: true,
+    // Keep the raw (un-resolved) name so validation can report the exact
+    // requested name — symmetric with `sourceHeading.templateAnnotation`.
+    sourceAnnotation: { template: rawTemplate, ...(hasParams ? { params } : {}) },
+    // Only carry a display title when the author supplied one.
+    ...(params.title ? { title: params.title } : {}),
+  };
+
+  if (hasParams) {
+    block.templateOverrides = params;
+    applyBlockMeta(block, coerceAnnotationValues(params).blockMeta);
+  }
+
+  return block;
+}
+
+/**
+ * Walk `contents`, lifting standalone template-annotation paragraphs into
+ * heading-less blocks. Nodes after an annotation (until the next annotation
+ * or the end of `contents`) attach to that block. Media annotations are left
+ * in place — they are extracted separately, before this runs. `contents` is
+ * not mutated; the split is returned.
+ */
+export function extractTemplateBlocksFromContents(
+  contents: MarkdownBlockNode[] | undefined,
+  options: StandaloneBlockOptions,
+): TemplateBlockExtraction {
+  const leading: MarkdownBlockNode[] = [];
+  const blocks: Block[] = [];
+  let current: Block | null = null;
+
+  for (const node of contents ?? []) {
+    const parsed = parseStandaloneAnnotation(node);
+    const isTemplateAnnotation =
+      parsed != null && parsed.template != null && !isMediaAnnotationName(parsed.template);
+
+    if (isTemplateAnnotation) {
+      const block = makeStandaloneBlock(parsed as ParsedAnnotation, options);
+      blocks.push(block);
+      current = block;
+    } else if (current) {
+      (current.contents ??= []).push(node);
+    } else {
+      leading.push(node);
+    }
+  }
+
+  return { leading, blocks };
+}

package/src/doc/customTemplatesFrontmatter.ts

@@ -0,0 +1,314 @@
+/**
+ * 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,
+  options?: { pretty?: boolean },
+): 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;
+  }
+  // Pretty output is multi-line, so it rides out as a YAML literal block
+  // scalar (see `formatBlockScalar` / stringify's frontmatter path) and
+  // parses back via `JSON.parse`. Default stays compact (single line) so
+  // existing docs and snapshots are byte-unchanged. The compact key codec
+  // (LONG_TO_SHORT) is applied in both modes.
+  return JSON.stringify(map, null, options?.pretty ? 2 : undefined);
+}
+
+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;
+}