@bendyline/squisq 1.5.0 → 1.5.2

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,
@@ -33,6 +39,8 @@ import {
   writeCustomThemesToFrontmatter,
 } from './customThemesFrontmatter.js';
 
+const TRANSITION_PARAM_KEYS = ['transition', 'transitionDuration', 'transitionDirection'] as const;
+
 /**
  * Convert a Doc with heading-driven blocks back to a MarkdownDocument.
  *
@@ -55,6 +63,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,61 +121,96 @@ 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.
  */
 function ensureAnnotation(block: Block, heading: MarkdownHeading): MarkdownHeading {
-  const attrs = ensureTransitionAttributes(block, heading);
+  const { attributes, transitionParams } = ensureTransitionMetadata(block, heading);
 
   // If the block has a non-default template or overrides, inject an annotation
   const hasExplicitTemplate =
     block.template && block.template !== 'sectionHeader' && block.autoTemplate !== true;
   const hasOverrides = block.templateOverrides && Object.keys(block.templateOverrides).length > 0;
 
-  // 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 };
+  let templateAnnotation = heading.templateAnnotation;
+  if (!templateAnnotation && (hasExplicitTemplate || hasOverrides || transitionParams)) {
+    templateAnnotation = {
+      ...(hasExplicitTemplate ? { template: block.template ?? 'sectionHeader' } : {}),
+      ...(hasOverrides ? { params: block.templateOverrides } : {}),
+    };
   }
 
-  if (!hasExplicitTemplate && !hasOverrides) {
-    return attrs === heading.attributes ? heading : { ...heading, attributes: attrs };
+  if (transitionParams) {
+    templateAnnotation = {
+      ...(templateAnnotation ?? {}),
+      params: {
+        ...(templateAnnotation?.params ?? {}),
+        ...transitionParams,
+      },
+    };
   }
 
-  // Clone to avoid mutating the original
-  return {
-    ...heading,
-    children: [...heading.children],
-    attributes: attrs,
-    templateAnnotation: {
-      template: block.template ?? 'sectionHeader',
-      ...(hasOverrides ? { params: block.templateOverrides } : {}),
-    },
-  };
+  if (attributes === heading.attributes && templateAnnotation === heading.templateAnnotation) {
+    return heading;
+  }
+
+  return { ...heading, children: [...heading.children], attributes, templateAnnotation };
 }
 
-function ensureTransitionAttributes(
+function ensureTransitionMetadata(
   block: Block,
   heading: MarkdownHeading,
-): MarkdownHeading['attributes'] {
+): {
+  attributes: MarkdownHeading['attributes'];
+  transitionParams: Record<string, string> | undefined;
+} {
   const transition = block.transition;
-  if (!transition) return heading.attributes;
+  if (!transition) {
+    return { attributes: heading.attributes, transitionParams: undefined };
+  }
 
-  const attrs = heading.attributes ?? {};
-  return {
+  // The transition is written to the squisq-native `{[…]}` params for
+  // author-facing markdown, and to `attributes.blockMeta` for the in-memory
+  // Doc → MarkdownDocument → Doc path (which does not re-parse string params).
+  const attrs = removeTransitionParams(heading.attributes) ?? {};
+  const attributes = {
     ...attrs,
-    params: {
-      ...(attrs.params ?? {}),
+    blockMeta: {
+      ...(attrs.blockMeta ?? {}),
+      transition,
+    },
+  };
+  return {
+    attributes,
+    transitionParams: {
       transition: transition.type,
       ...(transition.duration !== undefined
         ? { transitionDuration: String(transition.duration) }
         : {}),
       ...(transition.direction ? { transitionDirection: transition.direction } : {}),
     },
-    blockMeta: {
-      ...(attrs.blockMeta ?? {}),
-      transition,
-    },
+  };
+}
+
+function removeTransitionParams(
+  attrs: MarkdownHeading['attributes'],
+): MarkdownHeading['attributes'] {
+  if (!attrs?.params) return attrs;
+  const params = { ...attrs.params };
+  for (const key of TRANSITION_PARAM_KEYS) delete params[key];
+  return {
+    ...attrs,
+    ...(Object.keys(params).length > 0 ? { params } : { params: undefined }),
   };
 }

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';