@bendyline/squisq 1.4.1 → 1.5.1

package/src/__tests__/markdown.test.ts

@@ -11,6 +11,8 @@ import {
   countNodes,
   createDocument,
   parseFrontmatter,
+  setFrontmatterValues,
+  plainTextFromInlineHtml,
 } from '../markdown/index';
 import type {
   MarkdownDocument,
@@ -838,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', () => {
@@ -870,3 +935,25 @@ describe('frontmatter in parseMarkdown', () => {
     expect(doc.frontmatter).toBeUndefined();
   });
 });
+
+describe('plainTextFromInlineHtml', () => {
+  it('strips inline tags, keeping text', () => {
+    expect(plainTextFromInlineHtml('<strong>bold</strong> and <em>italic</em>')).toBe(
+      'bold and italic',
+    );
+  });
+
+  it('decodes entities', () => {
+    expect(plainTextFromInlineHtml('a &amp; b &lt;c&gt;')).toBe('a & b <c>');
+  });
+
+  it('turns <br> and block tags into line breaks', () => {
+    expect(plainTextFromInlineHtml('one<br>two')).toBe('one\ntwo');
+    expect(plainTextFromInlineHtml('<p>one</p><p>two</p>')).toBe('one\ntwo');
+    expect(plainTextFromInlineHtml('<h2>Title</h2><p>body</p>')).toBe('Title\nbody');
+  });
+
+  it('returns empty string for empty input', () => {
+    expect(plainTextFromInlineHtml('')).toBe('');
+  });
+});

package/src/__tests__/markdownSanitize.test.ts

@@ -0,0 +1,79 @@
+import { describe, expect, it } from 'vitest';
+import { parseHtmlToNodes, sanitizeHtmlNodes, sanitizeUrl } from '../markdown/index';
+import type { HtmlElement, HtmlNode } from '../markdown/index';
+
+function elements(nodes: HtmlNode[]): HtmlElement[] {
+  return nodes.filter((node): node is HtmlElement => node.type === 'htmlElement');
+}
+
+describe('markdown HTML sanitization', () => {
+  it('allows safe link URLs and rejects executable schemes', () => {
+    expect(sanitizeUrl('https://example.com', 'link')).toBe('https://example.com');
+    expect(sanitizeUrl('/docs/page.html#intro', 'link')).toBe('/docs/page.html#intro');
+    expect(sanitizeUrl('mailto:me@example.com', 'link')).toBe('mailto:me@example.com');
+    expect(sanitizeUrl('tel:+15551234567', 'link')).toBe('tel:+15551234567');
+    expect(sanitizeUrl('javascript:alert(1)', 'link')).toBeNull();
+    expect(sanitizeUrl('java\nscript:alert(1)', 'link')).toBeNull();
+    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');
+    expect(sanitizeUrl('data:audio/webm;base64,AAA', 'media')).toBe('data:audio/webm;base64,AAA');
+    expect(sanitizeUrl('data:image/svg+xml;base64,AAA', 'media')).toBeNull();
+    expect(sanitizeUrl('data:text/html,<script>alert(1)</script>', 'media')).toBeNull();
+  });
+
+  it('removes dangerous tags and event handler attributes', () => {
+    const safe = sanitizeHtmlNodes(
+      parseHtmlToNodes('<div onclick="alert(1)">ok<script>alert(1)</script></div>'),
+    );
+    const [div] = elements(safe);
+
+    expect(div.tagName).toBe('div');
+    expect(div.attributes.onclick).toBeUndefined();
+    expect(div.children).toEqual([{ type: 'htmlText', value: 'ok' }]);
+  });
+
+  it('sanitizes link and image attributes inside raw HTML', () => {
+    const safe = sanitizeHtmlNodes(
+      parseHtmlToNodes(
+        '<a href="javascript:alert(1)" target="_blank">bad</a><img src="x.jpg" onerror="alert(1)" width="300">',
+      ),
+    );
+    const [link, image] = elements(safe);
+
+    expect(link.tagName).toBe('a');
+    expect(link.attributes.href).toBeUndefined();
+    expect(link.attributes.target).toBe('_blank');
+    expect(link.attributes.rel).toBe('noopener noreferrer');
+    expect(image.tagName).toBe('img');
+    expect(image.attributes.src).toBe('x.jpg');
+    expect(image.attributes.onerror).toBeUndefined();
+    expect(image.attributes.width).toBe('300');
+  });
+
+  it('unwraps unknown harmless containers while keeping their safe children', () => {
+    const safe = sanitizeHtmlNodes(parseHtmlToNodes('<custom><strong>kept</strong></custom>'));
+    const [strong] = elements(safe);
+
+    expect(strong.tagName).toBe('strong');
+    expect(strong.children).toEqual([{ type: 'htmlText', value: 'kept' }]);
+  });
+});

package/src/__tests__/markdownToDoc.test.ts

@@ -4,6 +4,13 @@ import type { MarkdownText } from '../markdown/types';
 import { markdownToDoc, flattenBlocks, countBlocks, getBlockDepth } from '../doc/markdownToDoc';
 import { docToMarkdown } from '../doc/docToMarkdown';
 
+// Helper: parse markdown and return the first top-level block.
+function firstHeadingBlock(md: string) {
+  const parsed = parseMarkdown(md);
+  const doc = markdownToDoc(parsed, { articleId: 'test', generateCoverBlock: false });
+  return doc.blocks[0];
+}
+
 // Helper: strip positions from markdown nodes for cleaner assertions
 function stripPositions(obj: unknown): unknown {
   if (obj === null || obj === undefined) return obj;
@@ -243,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);
@@ -362,6 +394,61 @@ describe('template annotation in markdownToDoc', () => {
     expect(output).toContain('{[factCard style=minimal]}');
   });
 
+  it('docToMarkdown injects transition attributes from block metadata', () => {
+    const md = parseMarkdown('## Section\n\nBody');
+    const doc = markdownToDoc(md);
+    doc.blocks[0].transition = { type: 'wipe', duration: 0.8, direction: 'left' };
+
+    const output = stringifyMarkdown(docToMarkdown(doc));
+
+    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);
@@ -448,12 +535,16 @@ describe('caption generation', () => {
     expect(doc.captions).toBeUndefined();
   });
 
-  it('generates captions version and timestamp', () => {
+  it('generates captions version; timestamp only when supplied (deterministic default)', () => {
     const md = parseMarkdown('# Title\n\nHello world and more text.');
     const doc = markdownToDoc(md);
 
     expect(doc.captions!.version).toBe(1);
-    expect(doc.captions!.generatedAt).toBeTruthy();
+    // No clock reads during conversion — generatedAt is opt-in.
+    expect(doc.captions!.generatedAt).toBeUndefined();
+
+    const stamped = markdownToDoc(md, { captionsGeneratedAt: '2026-01-01T00:00:00.000Z' });
+    expect(stamped.captions!.generatedAt).toBe('2026-01-01T00:00:00.000Z');
   });
 
   it('caption phrases have sequential non-overlapping times', () => {
@@ -563,3 +654,301 @@ describe('auto cover block generation', () => {
     expect(doc.startBlock!.subtitle).toBeUndefined();
   });
 });
+
+describe('markdownToDoc with Pandoc attributes', () => {
+  it('overrides block id from {#id}', () => {
+    const block = firstHeadingBlock('## Section title {#intro}');
+    expect(block.id).toBe('intro');
+  });
+
+  it('applies x / y to typed Block fields', () => {
+    // `diagramNode` is a legacy alias for the canonical `diagram` template;
+    // the alias resolves at template-resolution time.
+    const block = firstHeadingBlock('## Step 1 {#step1 x=400 y=200} {[diagramNode]}');
+    expect(block.id).toBe('step1');
+    expect(block.x).toBe(400);
+    expect(block.y).toBe(200);
+    expect(block.template).toBe('diagram');
+  });
+
+  it('applies multiple connectsTo entries with mixed types', () => {
+    const block = firstHeadingBlock(
+      '## Architecture {#arch x=600 y=300 connectsTo=foo:veryImportant,bar:requires,baz:requires} {[diagramNode]}',
+    );
+    expect(block.connectsTo).toEqual([
+      { target: 'foo', type: 'veryImportant' },
+      { target: 'bar', type: 'requires' },
+      { target: 'baz', type: 'requires' },
+    ]);
+  });
+
+  it('parses connections without types', () => {
+    const block = firstHeadingBlock('## Summary {#summary connectsTo=intro,middle,end}');
+    expect(block.connectsTo).toEqual([
+      { target: 'intro' },
+      { target: 'middle' },
+      { target: 'end' },
+    ]);
+  });
+
+  it('parses mix of typed and untyped connections in one list', () => {
+    const block = firstHeadingBlock(
+      '## Decision {#decision connectsTo=alt1,alt2:rejected,alt3:chosen}',
+    );
+    expect(block.connectsTo).toEqual([
+      { target: 'alt1' },
+      { target: 'alt2', type: 'rejected' },
+      { target: 'alt3', type: 'chosen' },
+    ]);
+  });
+
+  it('overrides startTime / duration with attribute values (seconds)', () => {
+    const block = firstHeadingBlock('## Closing {#closing startTime=02:30 duration=00:45}');
+    expect(block.startTime).toBe(150);
+    expect(block.duration).toBe(45);
+  });
+
+  it('sets transition metadata from Pandoc attributes', () => {
+    const block = firstHeadingBlock(
+      '## Closing {#closing transition=checkerboard transitionDuration=1.2 transitionDirection=vertical}',
+    );
+    expect(block.transition).toEqual({
+      type: 'checkerboard',
+      duration: 1.2,
+      direction: 'vertical',
+    });
+  });
+
+  it('puts unknown keys into block.metadata', () => {
+    const block = firstHeadingBlock('## X {#x priority=high status=draft}');
+    expect(block.metadata).toEqual({ priority: 'high', status: 'draft' });
+  });
+
+  it('routes template params separately from block-level metadata', () => {
+    const block = firstHeadingBlock(
+      '## X {#big x=400 priority=high} {[diagramNode colorScheme=blue]}',
+    );
+    expect(block.templateOverrides).toEqual({ colorScheme: 'blue' });
+    expect(block.metadata).toEqual({ priority: 'high' });
+    expect(block.x).toBe(400);
+  });
+
+  it('stores Pandoc classes on block.classes', () => {
+    const block = firstHeadingBlock('## X {#x .alpha .beta}');
+    expect(block.classes).toEqual(['alpha', 'beta']);
+  });
+
+  it('backward compat: plain {[…]}-only heading is unchanged', () => {
+    const block = firstHeadingBlock('## X {[chart colorScheme=blue]}');
+    expect(block.template).toBe('chart');
+    expect(block.templateOverrides).toEqual({ colorScheme: 'blue' });
+    expect(block.x).toBeUndefined();
+    expect(block.metadata).toBeUndefined();
+    expect(block.classes).toBeUndefined();
+  });
+});
+
+describe('markdownToDoc block-meta in the squiggly {[…]} form', () => {
+  it('reads duration from a pure key-value {[duration=N]} annotation', () => {
+    const block = firstHeadingBlock('## Closing {[duration=8]}\n\nSome body text here.\n');
+    expect(block.duration).toBe(8);
+  });
+
+  it('does not let reading-time overwrite a squiggly-pinned duration', () => {
+    // Body long enough that the reading-time estimate would exceed 8s if it ran.
+    const body = Array(80).fill('word').join(' ');
+    const block = firstHeadingBlock(`## Closing {[duration=8]}\n\n${body}\n`);
+    expect(block.duration).toBe(8);
+  });
+
+  it('folds duration alongside a template name', () => {
+    const block = firstHeadingBlock('## Hero {[sectionHeader duration=6]}');
+    expect(block.template).toBe('sectionHeader');
+    expect(block.duration).toBe(6);
+  });
+
+  it('folds transition alongside a template name', () => {
+    const block = firstHeadingBlock(
+      '## Hero {[sectionHeader transition=fly-through transitionDuration=750ms]}',
+    );
+    expect(block.template).toBe('sectionHeader');
+    expect(block.transition).toEqual({
+      type: 'flyThrough',
+      duration: 0.75,
+    });
+  });
+
+  it('accepts startTime in the squiggly form too', () => {
+    const block = firstHeadingBlock('## Closing {[startTime=02:30 duration=45]}');
+    expect(block.startTime).toBe(150);
+    expect(block.duration).toBe(45);
+  });
+
+  it('Pandoc attrs win when a key appears in both forms', () => {
+    const block = firstHeadingBlock('## X {duration=3} {[duration=9]}');
+    expect(block.duration).toBe(3);
+  });
+});
+
+describe('auto template picking (autoTemplates, default on)', () => {
+  const toDocFromMd = (md: string, options?: Parameters<typeof markdownToDoc>[1]) =>
+    markdownToDoc(parseMarkdown(md), options);
+
+  it('picks quote for a blockquote-bearing section and derives the quote text', () => {
+    const doc = toDocFromMd('# Wisdom\n\n> The best template feels obvious.\n');
+    const block = doc.blocks[0];
+    expect(block.template).toBe('quote');
+    expect(block.autoTemplate).toBe(true);
+    expect(block.templateData?.quote).toBe('The best template feels obvious.');
+  });
+
+  it('picks dataTable for a table-bearing section with derived headers/rows', () => {
+    const doc = toDocFromMd('# Results\n\n| A | B |\n| - | - |\n| 1 | 2 |\n');
+    const block = doc.blocks[0];
+    expect(block.template).toBe('dataTable');
+    expect(block.templateData?.headers).toEqual(['A', 'B']);
+    expect(block.templateData?.rows).toEqual([['1', '2']]);
+  });
+
+  it('picks list for list-bearing sections and photoGrid for multi-image sections', () => {
+    const doc = toDocFromMd('# Steps\n\n- one\n- two\n\n# Gallery\n\n![a](a.jpg)\n\n![b](b.jpg)\n');
+    expect(doc.blocks[0].template).toBe('list');
+    expect(doc.blocks[0].templateData?.items).toEqual(['one', 'two']);
+    expect(doc.blocks[1].template).toBe('photoGrid');
+  });
+
+  it('alternates left/right feature for consecutive single-image sections', () => {
+    const doc = toDocFromMd('# One\n\n![a](a.jpg)\n\n# Two\n\n![b](b.jpg)\n');
+    expect(doc.blocks[0].template).toBe('leftFeature');
+    expect(doc.blocks[1].template).toBe('rightFeature');
+    expect(doc.blocks[0].templateData?.imageSrc).toBe('a.jpg');
+  });
+
+  it('leaves plain prose sections on the structural default', () => {
+    const doc = toDocFromMd('# About\n\nJust a paragraph of prose.\n');
+    expect(doc.blocks[0].template).toBe('sectionHeader');
+    expect(doc.blocks[0].autoTemplate).toBeUndefined();
+  });
+
+  it('never overrides an explicit annotation', () => {
+    const doc = toDocFromMd('# Wisdom {[factCard fact="F"]}\n\n> quoted\n');
+    expect(doc.blocks[0].template).toBe('factCard');
+  });
+
+  it('is disabled by the option and by frontmatter', () => {
+    const md = '# Wisdom\n\n> quoted\n';
+    const viaOption = toDocFromMd(md, { autoTemplates: false });
+    expect(viaOption.blocks[0].template).toBe('sectionHeader');
+
+    const viaFrontmatter = markdownToDoc(
+      parseMarkdown('---\nsquisq-auto-templates: false\n---\n\n' + md),
+    );
+    expect(viaFrontmatter.blocks[0].template).toBe('sectionHeader');
+  });
+
+  it('keeps the round-trip lossless (no materialized annotations)', () => {
+    const md = '# Wisdom\n\n> The best template feels obvious.\n';
+    const doc = toDocFromMd(md);
+    expect(doc.blocks[0].template).toBe('quote');
+    const roundTripped = stringifyMarkdown(docToMarkdown(doc));
+    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);
+  });
+});