@bendyline/squisq 1.5.0 → 1.5.1

package/src/__tests__/inputDescriptors.test.ts

@@ -0,0 +1,162 @@
+import { describe, it, expect } from 'vitest';
+import {
+  BASE_INPUT_DESCRIPTORS,
+  TEMPLATE_INPUT_DESCRIPTORS,
+  coerceTemplateParams,
+  lintTemplateParams,
+} from '../doc/templates/inputDescriptors';
+import { templateRegistry } from '../doc/templates/index';
+
+describe('coerceTemplateParams', () => {
+  it('coerces number keys, leaving the raw string on failure', () => {
+    expect(coerceTemplateParams('map', { zoom: '9' }).input).toEqual({ zoom: 9 });
+
+    const bad = coerceTemplateParams('map', { zoom: 'abc' });
+    expect(bad.input).toEqual({ zoom: 'abc' });
+    expect(bad.warnings).toHaveLength(1);
+    expect(bad.warnings[0]).toContain('zoom');
+  });
+
+  it('coerces boolean keys (true/empty → true, false → false)', () => {
+    const { input } = coerceTemplateParams('imageWithCaption', { isTitle: 'true' });
+    expect(input.isTitle).toBe(true);
+    // A bare flag `{[… isTitle]}` parses to an empty value → true.
+    expect(coerceTemplateParams('imageWithCaption', { isTitle: '' }).input.isTitle).toBe(true);
+    expect(coerceTemplateParams('imageWithCaption', { isTitle: 'false' }).input.isTitle).toBe(
+      false,
+    );
+
+    const bad = coerceTemplateParams('imageWithCaption', { isTitle: 'maybe' });
+    expect(bad.input.isTitle).toBe('maybe');
+    expect(bad.warnings).toHaveLength(1);
+  });
+
+  it('coerces latLng into { lat, lng }, warning on malformed input', () => {
+    expect(coerceTemplateParams('map', { center: '47.6,-122.3' }).input).toEqual({
+      center: { lat: 47.6, lng: -122.3 },
+    });
+
+    const bad = coerceTemplateParams('map', { center: 'nope' });
+    expect(bad.input).toEqual({ center: 'nope' });
+    expect(bad.warnings[0]).toContain('center');
+  });
+
+  it('coerces labeledPair into { label, sublabel? }', () => {
+    expect(coerceTemplateParams('twoColumn', { left: 'Espresso|Bold' }).input).toEqual({
+      left: { label: 'Espresso', sublabel: 'Bold' },
+    });
+    // No separator → label only, no sublabel key.
+    expect(coerceTemplateParams('twoColumn', { right: 'Filter' }).input).toEqual({
+      right: { label: 'Filter' },
+    });
+  });
+
+  it('coerces stringList by splitting on commas and trimming', () => {
+    expect(coerceTemplateParams('photoGrid', { images: 'a.jpg, b.jpg ,c.jpg' }).input).toEqual({
+      images: ['a.jpg', 'b.jpg', 'c.jpg'],
+    });
+  });
+
+  it('passes unknown keys through unchanged as strings (never lossy)', () => {
+    const { input, warnings } = coerceTemplateParams('map', { wobble: 'yes', center: '1,2' });
+    expect(input.wobble).toBe('yes');
+    expect(input.center).toEqual({ lat: 1, lng: 2 });
+    expect(warnings).toEqual([]);
+  });
+
+  it('passes everything through for a template with no descriptors', () => {
+    expect(coerceTemplateParams('sectionHeader', { anything: '5' }).input).toEqual({
+      anything: '5',
+    });
+  });
+
+  it('resolves legacy template aliases before coercing', () => {
+    expect(coerceTemplateParams('mapBlock', { zoom: '7' }).input).toEqual({ zoom: 7 });
+  });
+
+  it('coerces shared base inputs (useTopLayer boolean)', () => {
+    expect(coerceTemplateParams('title', { useTopLayer: 'false' }).input.useTopLayer).toBe(false);
+  });
+});
+
+describe('lintTemplateParams', () => {
+  it('returns [] for a template without descriptors', () => {
+    expect(lintTemplateParams('sectionHeader', { foo: 'bar' })).toEqual([]);
+  });
+
+  it('flags an unknown input with a did-you-mean suggestion', () => {
+    const findings = lintTemplateParams('map', { centre: '1,2' });
+    const unknown = findings.find((f) => f.kind === 'unknown-input');
+    expect(unknown).toBeDefined();
+    expect(unknown!.key).toBe('centre');
+    expect(unknown!.suggestion).toBe('center');
+    expect(unknown!.message).toContain('Did you mean "center"?');
+  });
+
+  it('does not flag block-meta keys carried on the same annotation', () => {
+    const findings = lintTemplateParams('title', { duration: '8', transition: 'fade' });
+    expect(findings.filter((f) => f.kind === 'unknown-input')).toEqual([]);
+  });
+
+  it('flags a value outside a closed enum', () => {
+    const findings = lintTemplateParams('map', { center: '1,2', mapStyle: 'nope' });
+    const invalid = findings.find((f) => f.kind === 'invalid-input-value');
+    expect(invalid).toBeDefined();
+    expect(invalid!.key).toBe('mapStyle');
+    expect(invalid!.message).toContain('terrain');
+  });
+
+  it('flags a value that fails coercion (bad latLng)', () => {
+    const findings = lintTemplateParams('map', { center: 'garbage' });
+    expect(findings.some((f) => f.kind === 'invalid-input-value' && f.key === 'center')).toBe(true);
+  });
+
+  it('flags missing required inputs', () => {
+    const findings = lintTemplateParams('twoColumn', {});
+    const missing = findings
+      .filter((f) => f.kind === 'missing-input')
+      .map((f) => f.key)
+      .sort();
+    expect(missing).toEqual(['left', 'right']);
+  });
+
+  it('does not flag a required input that is present', () => {
+    const findings = lintTemplateParams('map', { center: '1,2' });
+    expect(findings.filter((f) => f.kind === 'missing-input')).toEqual([]);
+  });
+
+  it('accepts a valid enum value', () => {
+    const findings = lintTemplateParams('map', { center: '1,2', mapStyle: 'satellite' });
+    expect(findings).toEqual([]);
+  });
+});
+
+describe('descriptor registry shape', () => {
+  it('base descriptors are declared with unique keys', () => {
+    const keys = BASE_INPUT_DESCRIPTORS.map((d) => d.key);
+    expect(new Set(keys).size).toBe(keys.length);
+  });
+
+  it('has no orphan descriptors — every keyed template exists in the registry', () => {
+    for (const template of Object.keys(TEMPLATE_INPUT_DESCRIPTORS)) {
+      expect(templateRegistry, `orphan descriptor for "${template}"`).toHaveProperty(template);
+    }
+  });
+
+  it('every template descriptor has unique keys and a description', () => {
+    for (const [template, descriptors] of Object.entries(TEMPLATE_INPUT_DESCRIPTORS)) {
+      const keys = descriptors.map((d) => d.key);
+      expect(new Set(keys).size, `duplicate key in ${template}`).toBe(keys.length);
+      for (const d of descriptors) {
+        expect(d.description.length, `empty description for ${template}.${d.key}`).toBeGreaterThan(
+          0,
+        );
+        // values / valueHint are mutually exclusive.
+        expect(
+          !(d.values && d.valueHint),
+          `${template}.${d.key} has both values and valueHint`,
+        ).toBe(true);
+      }
+    }
+  });
+});

package/src/__tests__/jsonForm.tokens.test.ts

@@ -0,0 +1,84 @@
+import { describe, it, expect } from 'vitest';
+import { buildJsonFormTokens, resolveJsonFormTheme } from '../jsonForm/index.js';
+import { DARK_SURFACE, LIGHT_SURFACE, DEFAULT_THEME, applySurface } from '../schemas/index.js';
+
+const EXPECTED_SUFFIXES = [
+  'bg',
+  'text',
+  'muted',
+  'primary',
+  'accent',
+  'warning',
+  'border',
+  'input-bg',
+  'title-font',
+  'body-font',
+  'mono-font',
+  'radius',
+];
+
+describe('buildJsonFormTokens', () => {
+  it('emits the full token set for the viewer prefix', () => {
+    const tokens = buildJsonFormTokens(DEFAULT_THEME, LIGHT_SURFACE, { prefix: '--squisq-json' });
+    for (const suffix of EXPECTED_SUFFIXES) {
+      expect(tokens).toHaveProperty(`--squisq-json-${suffix}`);
+    }
+    expect(Object.keys(tokens)).toHaveLength(EXPECTED_SUFFIXES.length);
+  });
+
+  it('emits the full token set for the editor prefix', () => {
+    const tokens = buildJsonFormTokens(DEFAULT_THEME, LIGHT_SURFACE, {
+      prefix: '--squisq-jsonform',
+    });
+    for (const suffix of EXPECTED_SUFFIXES) {
+      expect(tokens).toHaveProperty(`--squisq-jsonform-${suffix}`);
+    }
+    expect(Object.keys(tokens)).toHaveLength(EXPECTED_SUFFIXES.length);
+  });
+
+  it('resolves colors from the applied surface (light vs dark differ)', () => {
+    const light = buildJsonFormTokens(DEFAULT_THEME, LIGHT_SURFACE, { prefix: '--squisq-json' });
+    const dark = buildJsonFormTokens(DEFAULT_THEME, DARK_SURFACE, { prefix: '--squisq-json' });
+    const lightTheme = applySurface(DEFAULT_THEME, LIGHT_SURFACE);
+    const darkTheme = applySurface(DEFAULT_THEME, DARK_SURFACE);
+    expect(light['--squisq-json-bg']).toBe(lightTheme.colors.background);
+    expect(dark['--squisq-json-bg']).toBe(darkTheme.colors.background);
+    // The two surfaces should not produce an identical background.
+    expect(light['--squisq-json-bg']).not.toBe(dark['--squisq-json-bg']);
+  });
+
+  it('falls back to DEFAULT_THEME when theme is undefined', () => {
+    const tokens = buildJsonFormTokens(undefined, undefined, { prefix: '--squisq-json' });
+    expect(tokens['--squisq-json-bg']).toBe(DEFAULT_THEME.colors.background);
+  });
+
+  it('does not apply surface when surface is undefined', () => {
+    const tokens = buildJsonFormTokens(DEFAULT_THEME, undefined, { prefix: '--squisq-json' });
+    expect(tokens['--squisq-json-bg']).toBe(DEFAULT_THEME.colors.background);
+    expect(tokens['--squisq-json-radius']).toBe(`${DEFAULT_THEME.style.borderRadius ?? 8}px`);
+  });
+
+  it('is pure — no window/matchMedia access required', () => {
+    // Runs fine even if window is momentarily undefined-like; the function
+    // never touches globals.
+    expect(() =>
+      buildJsonFormTokens(DEFAULT_THEME, DARK_SURFACE, { prefix: '--squisq-json' }),
+    ).not.toThrow();
+  });
+});
+
+describe('resolveJsonFormTheme', () => {
+  it('applies the surface to the theme', () => {
+    expect(resolveJsonFormTheme(DEFAULT_THEME, DARK_SURFACE)).toEqual(
+      applySurface(DEFAULT_THEME, DARK_SURFACE),
+    );
+  });
+
+  it('returns the base theme untouched when surface is undefined', () => {
+    expect(resolveJsonFormTheme(DEFAULT_THEME, undefined)).toBe(DEFAULT_THEME);
+  });
+
+  it('falls back to DEFAULT_THEME when theme is undefined', () => {
+    expect(resolveJsonFormTheme(undefined, undefined)).toBe(DEFAULT_THEME);
+  });
+});

package/src/__tests__/markdown.test.ts

@@ -11,6 +11,7 @@ import {
   countNodes,
   createDocument,
   parseFrontmatter,
+  setFrontmatterValues,
   plainTextFromInlineHtml,
 } from '../markdown/index';
 import type {
@@ -839,6 +840,69 @@ describe('parseFrontmatter', () => {
     expect(parseFrontmatter('')).toBeNull();
     expect(parseFrontmatter('  \n  ')).toBeNull();
   });
+
+  it('parses a `|-` literal block scalar, dedenting the body', () => {
+    const result = parseFrontmatter('data: |-\n  line one\n  line two\ntitle: After');
+    expect(result).toEqual({ data: 'line one\nline two', title: 'After' });
+  });
+
+  it('parses a `|` literal block scalar (same joined value here)', () => {
+    const result = parseFrontmatter('data: |\n  a\n  b');
+    expect(result).toEqual({ data: 'a\nb' });
+  });
+
+  it('ends the block scalar at a line indented to the key or less', () => {
+    const result = parseFrontmatter('config: |-\n  {\n    "k": 1\n  }\nnext: x');
+    expect(result).toEqual({ config: '{\n  "k": 1\n}', next: 'x' });
+  });
+
+  it('parses multi-line pretty JSON as a block scalar back to a JSON string', () => {
+    const json = JSON.stringify({ hero: { lb: 'Hero' } }, null, 2);
+    const body = json
+      .split('\n')
+      .map((l) => `  ${l}`)
+      .join('\n');
+    const result = parseFrontmatter(`squisq-custom-templates: |-\n${body}`);
+    expect(typeof result!['squisq-custom-templates']).toBe('string');
+    expect(JSON.parse(result!['squisq-custom-templates'] as string)).toEqual({
+      hero: { lb: 'Hero' },
+    });
+  });
+
+  it('leaves single-line values untouched alongside block scalars', () => {
+    const result = parseFrontmatter('title: Plain\ninline: {"a":1}');
+    expect(result).toEqual({ title: 'Plain', inline: '{"a":1}' });
+  });
+});
+
+describe('multi-line frontmatter round-trips', () => {
+  it('round-trips a multi-line string value through stringify → parse', () => {
+    const value = JSON.stringify({ a: 1, b: [2, 3] }, null, 2);
+    const doc = createDocument();
+    doc.frontmatter = { payload: value, title: 'Doc' };
+    const md = stringifyMarkdown(doc);
+    expect(md).toContain('payload: |-');
+    const reparsed = parseMarkdown(md);
+    expect(reparsed.frontmatter!.payload).toBe(value);
+    expect(reparsed.frontmatter!.title).toBe('Doc');
+  });
+
+  it('setFrontmatterValues emits a block scalar for a multi-line value', () => {
+    const value = 'one\ntwo\nthree';
+    const out = setFrontmatterValues('# Body\n', { notes: value });
+    expect(out).toContain('notes: |-');
+    expect(out).toContain('  one');
+    const doc = parseMarkdown(out);
+    expect(doc.frontmatter!.notes).toBe(value);
+  });
+
+  it('keeps single-line frontmatter output unchanged', () => {
+    const doc = createDocument();
+    doc.frontmatter = { 'document-render-as': 'portrait' };
+    const md = stringifyMarkdown(doc);
+    expect(md).toContain('document-render-as: portrait');
+    expect(md).not.toContain('|-');
+  });
 });
 
 describe('frontmatter in parseMarkdown', () => {

package/src/__tests__/markdownSanitize.test.ts

@@ -17,6 +17,21 @@ describe('markdown HTML sanitization', () => {
     expect(sanitizeUrl('data:text/html,<script>alert(1)</script>', 'link')).toBeNull();
   });
 
+  it('extraLinkSchemes allows host-app schemes but never executable ones', () => {
+    expect(sanitizeUrl('gezel-nav:src%2Fa.ts', 'link')).toBeNull();
+    expect(sanitizeUrl('gezel-nav:src%2Fa.ts', 'link', { extraLinkSchemes: ['gezel-nav'] })).toBe(
+      'gezel-nav:src%2Fa.ts',
+    );
+    expect(
+      sanitizeUrl('javascript:alert(1)', 'link', { extraLinkSchemes: ['javascript'] }),
+    ).toBeNull();
+    expect(sanitizeUrl('data:text/html,x', 'link', { extraLinkSchemes: ['data'] })).toBeNull();
+    // media URLs ignore the option entirely
+    expect(
+      sanitizeUrl('gezel-nav:src%2Fa.ts', 'media', { extraLinkSchemes: ['gezel-nav'] }),
+    ).toBeNull();
+  });
+
   it('allows Squisq media URLs without allowing SVG or HTML data payloads', () => {
     expect(sanitizeUrl('blob:http://localhost/abc', 'media')).toBe('blob:http://localhost/abc');
     expect(sanitizeUrl('data:image/png;base64,AAA', 'media')).toBe('data:image/png;base64,AAA');

package/src/__tests__/markdownToDoc.test.ts

@@ -250,6 +250,31 @@ describe('docToMarkdown (round-trip)', () => {
     expect(stripPositions(md2)).toEqual(stripPositions(md));
   });
 
+  it('round-trips inline coerced template params, keeping overrides raw', () => {
+    const input = '# Downtown {[map center="47.6,-122.3" zoom=9 mapStyle="road"]}\n\nSome text.\n';
+    const md = parseMarkdown(input);
+    const doc = markdownToDoc(md, { generateCoverBlock: false });
+
+    // The overrides must stay RAW strings — coercion only ever touches the
+    // ephemeral render input, never the stored block, so round-trips are lossless.
+    expect(doc.blocks[0].templateOverrides).toEqual({
+      center: '47.6,-122.3',
+      zoom: '9',
+      mapStyle: 'road',
+    });
+
+    // Byte-stable: one full cycle reaches a fixed point that a second cycle
+    // reproduces exactly.
+    const once = stringifyMarkdown(docToMarkdown(doc));
+    const twice = stringifyMarkdown(
+      docToMarkdown(markdownToDoc(parseMarkdown(once), { generateCoverBlock: false })),
+    );
+    expect(twice).toBe(once);
+    // And the annotation with its raw values survives serialization.
+    expect(once).toContain('center=47.6,-122.3');
+    expect(once).toContain('zoom=9');
+  });
+
   it('round-trips preamble content', () => {
     const input = 'Preamble text\n\n# Heading\n\nBody\n';
     const md = parseMarkdown(input);
@@ -379,6 +404,51 @@ describe('template annotation in markdownToDoc', () => {
     expect(output).toContain('{transition=wipe transitionDuration=0.8 transitionDirection=left}');
   });
 
+  it('a programmatic transition survives the string round trip', () => {
+    const doc = markdownToDoc(parseMarkdown('## Section\n\nBody'));
+    doc.blocks[0].transition = { type: 'wipe', duration: 0.8, direction: 'left' };
+
+    const reparsed = markdownToDoc(parseMarkdown(stringifyMarkdown(docToMarkdown(doc))));
+
+    expect(reparsed.blocks[0].transition).toEqual({
+      type: 'wipe',
+      duration: 0.8,
+      direction: 'left',
+    });
+  });
+
+  it('a programmatic transition survives the in-memory round trip (no stringify)', () => {
+    // markdownToDoc reads heading.attributes.blockMeta directly — it never
+    // re-coerces params — so docToMarkdown must keep blockMeta in sync with
+    // the params it writes for stringifyMarkdown.
+    const doc = markdownToDoc(parseMarkdown('## Section\n\nBody'));
+    doc.blocks[0].transition = { type: 'wipe', duration: 0.8, direction: 'left' };
+
+    const reconverted = markdownToDoc(docToMarkdown(doc));
+
+    expect(reconverted.blocks[0].transition).toEqual({
+      type: 'wipe',
+      duration: 0.8,
+      direction: 'left',
+    });
+  });
+
+  it('an updated transition replaces a previously authored one in both round trips', () => {
+    // The heading already carries a parsed transition (params + blockMeta);
+    // a programmatic change must win over the stale blockMeta.
+    const doc = markdownToDoc(parseMarkdown('## Section {transition=fade}\n\nBody'));
+    expect(doc.blocks[0].transition).toEqual({ type: 'fade' });
+    doc.blocks[0].transition = { type: 'wipe', direction: 'left' };
+
+    const inMemory = markdownToDoc(docToMarkdown(doc));
+    expect(inMemory.blocks[0].transition).toEqual({ type: 'wipe', direction: 'left' });
+
+    const output = stringifyMarkdown(docToMarkdown(doc));
+    expect(output).toContain('transition=wipe');
+    const reparsed = markdownToDoc(parseMarkdown(output));
+    expect(reparsed.blocks[0].transition).toEqual({ type: 'wipe', direction: 'left' });
+  });
+
   it('nested headings preserve their own annotations', () => {
     const input = '# Chapter {[title]}\n\nIntro\n\n## Section {[chart]}\n\nData';
     const md = parseMarkdown(input);
@@ -784,3 +854,101 @@ describe('auto template picking (autoTemplates, default on)', () => {
     expect(roundTripped).not.toContain('{[quote');
   });
 });
+
+describe('standalone annotation blocks (S2)', () => {
+  const toDoc = (md: string, options?: Parameters<typeof markdownToDoc>[1]) =>
+    markdownToDoc(parseMarkdown(md), { articleId: 't', generateCoverBlock: false, ...options });
+
+  it('turns a standalone {[template]} paragraph into a heading-less block', () => {
+    const doc = toDoc('# Intro\n\nlead para\n\n{[quote]}\n\nquoted body\n');
+    // Containing block keeps only the leading content.
+    const intro = doc.blocks[0];
+    expect(intro.title).toBe('Intro');
+    expect(intro.contents?.map((n) => n.type)).toEqual(['paragraph']);
+    // The produced block is a sibling right after the containing block.
+    const q = doc.blocks[1];
+    expect(q.template).toBe('quote');
+    expect(q.standaloneAnnotation).toBe(true);
+    expect(q.sourceHeading).toBeUndefined();
+    expect(q.sourceAnnotation).toEqual({ template: 'quote' });
+    expect(q.contents?.map((n) => n.type)).toEqual(['paragraph']);
+  });
+
+  it('attaches trailing contents up to the next annotation; params → overrides + title', () => {
+    const doc = toDoc(
+      '# H\n\n{[statHighlight title="Q1 Revenue" colorScheme=blue]}\n\nbig number\n\n{[quote]}\n\nq\n',
+    );
+    const stat = doc.blocks[1];
+    expect(stat.template).toBe('statHighlight');
+    expect(stat.title).toBe('Q1 Revenue');
+    expect(stat.templateOverrides).toEqual({ title: 'Q1 Revenue', colorScheme: 'blue' });
+    expect(stat.contents?.length).toBe(1); // "big number", ended by the next annotation
+    const quote = doc.blocks[2];
+    expect(quote.template).toBe('quote');
+    expect(quote.contents?.length).toBe(1); // "q"
+  });
+
+  it('produces adjacent blocks for consecutive annotations (no content between)', () => {
+    const doc = toDoc('# H\n\n{[quote]}\n\n{[factCard]}\n\ntail\n');
+    expect(doc.blocks[1].template).toBe('quote');
+    expect(doc.blocks[1].contents ?? []).toHaveLength(0);
+    expect(doc.blocks[2].template).toBe('factCard');
+    expect(doc.blocks[2].contents?.length).toBe(1); // "tail"
+  });
+
+  it('handles an annotation as the last node (no trailing contents)', () => {
+    const doc = toDoc('# H\n\nbody\n\n{[quote]}\n');
+    expect(doc.blocks[1].template).toBe('quote');
+    expect(doc.blocks[1].contents ?? []).toHaveLength(0);
+  });
+
+  it('generates unique slug ids that dedupe against headings', () => {
+    const doc = toDoc('# Quote\n\n{[quote title=Quote]}\n\nbody\n');
+    expect(doc.blocks[0].id).toBe('quote');
+    expect(doc.blocks[1].id).toBe('quote-2');
+  });
+
+  it('lifts an annotation out of the preamble (before the first heading)', () => {
+    const doc = toDoc('intro\n\n{[quote]}\n\nquoted\n\n# Heading\n\nrest\n');
+    // preamble keeps "intro", quote block next, then the heading block.
+    expect(doc.blocks[0].sourceHeading).toBeUndefined();
+    expect(doc.blocks[0].contents?.length).toBe(1);
+    expect(doc.blocks[1].template).toBe('quote');
+    expect(doc.blocks[2].title).toBe('Heading');
+  });
+
+  it('drops a preamble that was entirely a standalone annotation', () => {
+    const doc = toDoc('{[quote]}\n\nquoted\n\n# Heading\n');
+    expect(doc.blocks[0].template).toBe('quote');
+    expect(doc.blocks[0].standaloneAnnotation).toBe(true);
+    expect(doc.blocks[1].title).toBe('Heading');
+  });
+
+  it('honors a pinned duration on a standalone annotation', () => {
+    const doc = toDoc('# H\n\n{[quote duration=9]}\n\nbody\n');
+    expect(doc.blocks[1].duration).toBe(9);
+  });
+
+  it('does not treat annotations nested inside a list as blocks', () => {
+    const doc = toDoc('# H\n\n- {[quote]}\n');
+    // Only the heading block — the list annotation stays in contents.
+    expect(doc.blocks).toHaveLength(1);
+    expect(doc.blocks[0].contents?.[0].type).toBe('list');
+  });
+
+  it('round-trips a standalone annotation block byte-for-byte', () => {
+    const md = '# Intro\n\nlead\n\n{[quote]}\n\nquoted body\n';
+    const doc = toDoc(md);
+    const out = stringifyMarkdown(docToMarkdown(doc));
+    expect(out).toBe(md);
+    // And re-parsing is stable.
+    const doc2 = toDoc(out);
+    expect(stringifyMarkdown(docToMarkdown(doc2))).toBe(md);
+  });
+
+  it('round-trips params (quoting) byte-for-byte', () => {
+    const md = '# H\n\n{[statHighlight title="Q1 Revenue" colorScheme=blue]}\n\nbody\n';
+    const out = stringifyMarkdown(docToMarkdown(toDoc(md)));
+    expect(out).toBe(md);
+  });
+});

package/src/__tests__/mediaAnnotations.test.ts

@@ -44,6 +44,14 @@ describe('markdownToDoc media annotations', () => {
     });
   });
 
+  it('accepts startTime as an alias of startAt (startAt wins when both given)', () => {
+    const alias = toDoc('# B {duration=20}\n\n{[audio src=a.mp3 startTime=5]}\n');
+    expect(alias.blocks[0].media![0].startAt).toBe(5);
+
+    const both = toDoc('# B {duration=20}\n\n{[audio src=a.mp3 startAt=3 startTime=5]}\n');
+    expect(both.blocks[0].media![0].startAt).toBe(3);
+  });
+
   it('media annotation text does not inflate block duration', () => {
     // No explicit duration; body is only the annotation → default (5s), not reading-time of the annotation text.
     const doc = toDoc('# B\n\n{[audio src=a.mp3]}\n');
@@ -62,3 +70,22 @@ describe('markdownToDoc media annotations', () => {
     expect(block.absoluteStart).toBe(35); // block Two at 30 + startAt 5
   });
 });
+
+describe('media annotations vs standalone template blocks', () => {
+  it('extracts media annotations as clips, not standalone blocks (media names win)', () => {
+    const doc = toDoc('# One\n\nIntro.\n\n{[audio src=narration.mp3]}\n\n{[video src=clip.mp4]}\n');
+    const block = doc.blocks[0];
+    expect(block.media?.map((m) => m.kind)).toEqual(['audio', 'video']);
+    // No sibling standalone blocks were produced for the media names.
+    expect(doc.blocks).toHaveLength(1);
+    expect(doc.blocks.some((b) => b.standaloneAnnotation)).toBe(false);
+  });
+
+  it('mixes a media clip and a standalone template block in one section', () => {
+    const doc = toDoc('# One\n\n{[audio src=n.mp3]}\n\n{[quote]}\n\nquoted\n');
+    expect(doc.blocks[0].media?.map((m) => m.kind)).toEqual(['audio']);
+    const q = doc.blocks[1];
+    expect(q.template).toBe('quote');
+    expect(q.standaloneAnnotation).toBe(true);
+  });
+});

package/src/__tests__/structuredData.test.ts

@@ -1,7 +1,8 @@
 import { describe, it, expect } from 'vitest';
 import { parseMarkdown } from '../markdown/parse.js';
 import { markdownToDoc } from '../doc/markdownToDoc.js';
-import { parseYamlSubset } from '../doc/structuredData.js';
+import { parseYamlSubset, replaceDataFence } from '../doc/structuredData.js';
+import type { MarkdownCodeBlock } from '../markdown/types.js';
 
 function toDoc(md: string) {
   return markdownToDoc(parseMarkdown(md));
@@ -41,8 +42,21 @@ describe('parseYamlSubset', () => {
     expect(parseYamlSubset('# comment\n\nkey: value')).toEqual({ key: 'value' });
   });
 
-  it('rejects nested mappings with a line-anchored error', () => {
-    expect(() => parseYamlSubset('outer:\n  inner: 1')).toThrow(/line 2/);
+  it('parses one level of nested mapping', () => {
+    expect(parseYamlSubset('center:\n  lat: 47.6\n  lng: -122.3\nzoom: 12')).toEqual({
+      center: { lat: 47.6, lng: -122.3 },
+      zoom: 12,
+    });
+  });
+
+  it('rejects nesting deeper than one level with a line-anchored error', () => {
+    expect(() => parseYamlSubset('a:\n  b:\n    c: 1')).toThrow(/line 2/);
+    expect(() => parseYamlSubset('a:\n  b: 1\n    c: 2')).toThrow(/line 3/);
+  });
+
+  it('rejects mixing list items and mapping keys under one key', () => {
+    expect(() => parseYamlSubset('a:\n  - x\n  b: 1')).toThrow(/mix/);
+    expect(() => parseYamlSubset('a:\n  b: 1\n  - x')).toThrow(/mix/);
   });
 });
 
@@ -93,6 +107,62 @@ describe('data fences → block.templateData', () => {
   });
 });
 
+describe('replaceDataFence', () => {
+  it('replaces the first data fence content, keeping lang and meta', () => {
+    const doc = toDoc(
+      '## Numbers {[dataTable]}\n\nIntro.\n\n```json data\n{ "headers": ["Q"] }\n```',
+    );
+    const contents = doc.blocks[0].contents!;
+
+    const next = replaceDataFence(contents, { headers: ['Q', 'Revenue'] });
+
+    const fence = next.find((n): n is MarkdownCodeBlock => n.type === 'code')!;
+    expect(fence.lang).toBe('json');
+    expect(fence.meta).toBe('data');
+    expect(JSON.parse(fence.value)).toEqual({ headers: ['Q', 'Revenue'] });
+    // Pretty-printed, not single-line.
+    expect(fence.value).toContain('\n');
+    // Same length, other nodes untouched.
+    expect(next).toHaveLength(contents.length);
+    expect(next[0]).toBe(contents[0]);
+  });
+
+  it('does not mutate the input array or the original fence node', () => {
+    const doc = toDoc('## Numbers {[dataTable]}\n\n```json data\n{ "a": 1 }\n```');
+    const contents = doc.blocks[0].contents!;
+    const originalFence = contents.find((n): n is MarkdownCodeBlock => n.type === 'code')!;
+
+    replaceDataFence(contents, { a: 2 });
+
+    expect(originalFence.value).toBe('{ "a": 1 }');
+  });
+
+  it('appends a new ```json data fence when none exists', () => {
+    const doc = toDoc('## Numbers {[dataTable]}\n\nJust text.');
+    const contents = doc.blocks[0].contents!;
+
+    const next = replaceDataFence(contents, { rows: [['Q1', '1.2M']] });
+
+    expect(next).toHaveLength(contents.length + 1);
+    const fence = next[next.length - 1] as MarkdownCodeBlock;
+    expect(fence).toMatchObject({ type: 'code', lang: 'json', meta: 'data' });
+    expect(JSON.parse(fence.value)).toEqual({ rows: [['Q1', '1.2M']] });
+  });
+
+  it('treats plain code fences (no data marker) as non-fences and appends', () => {
+    const doc = toDoc('## Code {[sectionHeader]}\n\n```json\n{ "just": "a sample" }\n```');
+    const contents = doc.blocks[0].contents!;
+
+    const next = replaceDataFence(contents, { a: 1 });
+
+    // The sample fence is untouched; a data fence is appended after it.
+    const sample = next.find((n): n is MarkdownCodeBlock => n.type === 'code' && !n.meta)!;
+    expect(sample.value).toBe('{ "just": "a sample" }');
+    expect(next).toHaveLength(contents.length + 1);
+    expect((next[next.length - 1] as MarkdownCodeBlock).meta).toBe('data');
+  });
+});
+
 describe('dataTable eats GFM tables', () => {
   const table = ['| Name | Age |', '| --- | ---: |', '| Alice | 30 |', '| Bob | 25 |'].join('\n');