@bendyline/squisq 1.5.0 → 1.5.1

package/src/__tests__/templateMetadata.test.ts

@@ -1,5 +1,5 @@
 import { describe, it, expect } from 'vitest';
-import { templateRegistry, TEMPLATE_METADATA } from '../doc/templates/index';
+import { templateRegistry, TEMPLATE_METADATA, TEMPLATE_ALIASES } from '../doc/templates/index';
 
 describe('TEMPLATE_METADATA', () => {
   it('stays exactly 1:1 with templateRegistry (same ids)', () => {
@@ -19,3 +19,13 @@ describe('TEMPLATE_METADATA', () => {
     }
   });
 });
+
+describe('TEMPLATE_ALIASES', () => {
+  it('every alias target resolves to a real registry entry', () => {
+    // A typo'd alias target would otherwise fall through resolveTemplateName's
+    // `?? name` fallback and silently resolve to a non-existent template.
+    for (const [alias, target] of Object.entries(TEMPLATE_ALIASES)) {
+      expect(target in templateRegistry, `alias "${alias}" → "${target}"`).toBe(true);
+    }
+  });
+});

package/src/__tests__/templates.test.ts

@@ -10,6 +10,10 @@ import {
   VIEWPORT_PRESETS,
 } from '../doc/templates/index';
 import type { TemplateBlock } from '../schemas/BlockTemplates';
+import type { TextLayer } from '../schemas/Doc';
+import { getLayers } from '../doc/getLayers';
+import { markdownToDoc } from '../doc/markdownToDoc';
+import { parseMarkdown } from '../markdown/parse';
 
 describe('templateRegistry', () => {
   it('contains all expected templates', () => {
@@ -244,6 +248,75 @@ describe('expandTemplateBlock', () => {
       expect((result.layers ?? []).length).toBeGreaterThanOrEqual(1);
     }
   });
+
+  it('keeps photoGrid media captions compact without placeholder alt labels', () => {
+    const block: TemplateBlock = {
+      template: 'photoGrid',
+      id: 'photo-grid-captions',
+      duration: 10,
+      audioSegment: 0,
+      images: [
+        { src: 'one.jpg', alt: 'A long archival caption for the first image' },
+        { src: 'two.jpg', alt: 'A long archival caption for the second image' },
+        { src: 'three.jpg', alt: 'A long archival caption for the third image' },
+      ],
+      caption:
+        'A long Wikimedia description with source notes, place names, dates, and details that should remain compact.',
+    };
+
+    const context = createTemplateContext(DEFAULT_THEME, 0, 10, VIEWPORT_PRESETS.landscape);
+    const result = expandTemplateBlock(block, context);
+    const layers = result.layers ?? [];
+    const captionLayer = layers.find(
+      (layer): layer is TextLayer => layer.type === 'text' && layer.id === 'caption',
+    );
+
+    expect(layers.some((layer) => layer.id.startsWith('grid-alt-'))).toBe(false);
+    expect(captionLayer).toBeDefined();
+    expect(captionLayer!.content.style.maxLines).toBe(1);
+    expect(captionLayer!.position.width).toBe('78%');
+  });
+
+  it('clamps full-bleed media captions above playback controls', () => {
+    const imageBlock: TemplateBlock = {
+      template: 'imageWithCaption',
+      id: 'image-caption',
+      duration: 10,
+      audioSegment: 0,
+      imageSrc: 'image.jpg',
+      imageAlt: 'Image',
+      caption:
+        'A long Wikimedia description with source notes, place names, dates, and details that should remain compact.',
+    };
+    const videoBlock: TemplateBlock = {
+      template: 'videoWithCaption',
+      id: 'video-caption',
+      duration: 10,
+      audioSegment: 0,
+      videoSrc: 'video.mp4',
+      videoAlt: 'Video',
+      clipStart: 0,
+      clipEnd: 10,
+      caption: imageBlock.caption,
+    };
+
+    const context = createTemplateContext(DEFAULT_THEME, 0, 10, VIEWPORT_PRESETS.landscape);
+    const imageCaption = (expandTemplateBlock(imageBlock, context).layers ?? []).find(
+      (layer): layer is TextLayer => layer.type === 'text' && layer.id === 'caption',
+    );
+    const videoCaption = (expandTemplateBlock(videoBlock, context).layers ?? []).find(
+      (layer): layer is TextLayer => layer.type === 'text' && layer.id === 'caption',
+    );
+
+    expect(imageCaption).toBeDefined();
+    expect(videoCaption).toBeDefined();
+    expect(imageCaption!.content.style.maxLines).toBe(2);
+    expect(videoCaption!.content.style.maxLines).toBe(2);
+    expect(imageCaption!.position.y).toBe('74%');
+    expect(videoCaption!.position.y).toBe('74%');
+    expect(imageCaption!.position.width).toBe('78%');
+    expect(videoCaption!.position.width).toBe('78%');
+  });
 });
 
 describe('expandDocBlocks', () => {
@@ -460,6 +533,45 @@ describe('DEFAULT_THEME', () => {
   });
 });
 
+describe('inline-param coercion → getLayers', () => {
+  function firstBlock(md: string) {
+    return markdownToDoc(parseMarkdown(md), { generateCoverBlock: false }).blocks[0];
+  }
+
+  it('renders a map from pure-inline {[map center=… zoom=…]} annotation', () => {
+    const block = firstBlock('# Downtown {[map center="47.6,-122.3" zoom=9 mapStyle="road"]}\n');
+    // Raw overrides stay strings for lossless round-trip.
+    expect(block.templateOverrides).toEqual({
+      center: '47.6,-122.3',
+      zoom: '9',
+      mapStyle: 'road',
+    });
+
+    const layers = getLayers(block, {});
+    const mapLayer = layers.find((l) => l.type === 'map');
+    expect(mapLayer).toBeDefined();
+    // Coerced center/zoom flow into the map layer's content — not empty strings.
+    const content = mapLayer!.content as { center: { lat: number; lng: number }; zoom: number };
+    expect(content.center).toEqual({ lat: 47.6, lng: -122.3 });
+    expect(content.zoom).toBe(9);
+  });
+
+  it('renders a twoColumn from pure-inline labeled-pair annotation', () => {
+    const block = firstBlock('# Coffee {[twoColumn left="Espresso|Bold" right="Filter|Smooth"]}\n');
+    const layers = getLayers(block, {});
+    // Guard requires both labels — a non-empty layer set proves coercion worked.
+    expect(layers.length).toBeGreaterThan(0);
+    const texts = layers
+      .filter((l) => l.type === 'text')
+      .map((l) => (l.content as { text: string }).text);
+    expect(texts).toContain('Espresso');
+    expect(texts).toContain('Filter');
+    // The sublabels from the "|" split render too.
+    expect(texts).toContain('Bold');
+    expect(texts).toContain('Smooth');
+  });
+});
+
 describe('VIEWPORT_PRESETS', () => {
   it('has landscape and portrait presets', () => {
     expect(VIEWPORT_PRESETS).toHaveProperty('landscape');

package/src/__tests__/validateDoc.test.ts

@@ -1,5 +1,7 @@
 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);
@@ -11,6 +13,7 @@ describe('validateMarkdownSource — templates', () => {
     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', () => {
@@ -71,6 +74,43 @@ describe('validateMarkdownSource — attributes and structure', () => {
   });
 });
 
+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', {
@@ -98,3 +138,123 @@ describe('validateMarkdownSource — assets', () => {
     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

@@ -225,6 +225,7 @@ export function readCustomTemplatesFromFrontmatter(
  */
 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>> = {};
@@ -235,7 +236,12 @@ export function writeCustomTemplatesToFrontmatter(
     entry.ly = renameKeys(def.layers, LONG_TO_SHORT);
     map[def.name] = entry;
   }
-  return JSON.stringify(map);
+  // 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 } {

package/src/doc/customThemesFrontmatter.ts

@@ -82,9 +82,14 @@ export function readCustomThemesFromFrontmatter(
  */
 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;
-  return JSON.stringify(map);
+  // 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,13 @@
  */
 
 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,
@@ -55,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
@@ -107,6 +119,16 @@ export function docToMarkdown(doc: Doc): MarkdownDocument {
   };
 }
 
+/**
+ * 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.
@@ -148,6 +170,14 @@ function ensureTransitionAttributes(
   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,

package/src/doc/getLayers.ts

@@ -35,6 +35,7 @@ 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 { coerceTemplateParams } from './templates/inputDescriptors.js';
 import { expandPersistentLayers, wrapWithPersistentLayers } from './templates/persistentLayers.js';
 import { applyRenderStyleToLayers } from './utils/applyRenderStyle.js';
 import { fallbackBlockLayers } from './templates/fallbackBlock.js';
@@ -121,11 +122,19 @@ export function getLayers(block: DocBlock, context: RenderContext = {}): Layer[]
       }
       // 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.
+      // 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, ...templateOverrides } as TemplateBlock)
+          ? ({
+              ...block,
+              ...templateData,
+              ...coerceTemplateParams(block.template, templateOverrides ?? {}).input,
+            } as TemplateBlock)
           : block;
       let layers: Layer[];
       try {

package/src/doc/index.ts

@@ -33,6 +33,7 @@ export { resolveAudioMapping, scoreTextSimilarity } from './audioMapping.js';
 export {
   isDataFence,
   parseDataFence,
+  replaceDataFence,
   parseYamlSubset,
   findFirstTable,
   extractTableData,
@@ -41,3 +42,14 @@ export type { DataFenceParseResult, ExtractedTableData } from './structuredData.
 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';