@bendyline/squisq 1.4.0 → 1.5.0

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;
@@ -362,6 +369,16 @@ 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('nested headings preserve their own annotations', () => {
     const input = '# Chapter {[title]}\n\nIntro\n\n## Section {[chart]}\n\nData';
     const md = parseMarkdown(input);
@@ -448,12 +465,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 +584,203 @@ 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');
+  });
+});

package/src/__tests__/mediaAnnotations.test.ts

@@ -0,0 +1,64 @@
+import { describe, expect, it } from 'vitest';
+import { parseMarkdown } from '../markdown/parse.js';
+import { markdownToDoc } from '../doc/markdownToDoc.js';
+import { resolveMediaSchedule } from '../schemas/Media.js';
+
+function toDoc(md: string) {
+  return markdownToDoc(parseMarkdown(md), { articleId: 't' });
+}
+
+describe('markdownToDoc media annotations', () => {
+  it('lifts a block-level audio annotation into block.media', () => {
+    const doc = toDoc(
+      '# One {duration=10}\n\nIntro.\n\n{[audio src=narration.mp3 startAt=5 clipEnd=8 spillover=true]}\n',
+    );
+    const block = doc.blocks[0];
+    expect(block.media).toHaveLength(1);
+    expect(block.media![0]).toMatchObject({
+      src: 'narration.mp3',
+      kind: 'audio',
+      startAt: 5,
+      clipEnd: 8,
+      spillover: true,
+      anchor: 'block',
+    });
+    // The annotation paragraph is removed from the visible contents.
+    expect(JSON.stringify(block.contents)).not.toContain('narration.mp3');
+  });
+
+  it('routes anchor=document annotations to doc.documentMedia', () => {
+    const doc = toDoc('{[audio src=voice.mp3 anchor=document]}\n\n# First\n\nBody.\n');
+    expect(doc.documentMedia).toHaveLength(1);
+    expect(doc.documentMedia![0]).toMatchObject({ src: 'voice.mp3', anchor: 'document' });
+    // It is not also attached to the preamble block's media.
+    expect(doc.blocks[0].media).toBeUndefined();
+  });
+
+  it('recognizes a video annotation as kind video', () => {
+    const doc = toDoc('# B {duration=20}\n\n{[video src=clip.mp4 clipStart=2 clipEnd=8]}\n');
+    expect(doc.blocks[0].media![0]).toMatchObject({
+      src: 'clip.mp4',
+      kind: 'video',
+      clipStart: 2,
+      clipEnd: 8,
+    });
+  });
+
+  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');
+    expect(doc.blocks[0].duration).toBe(5);
+  });
+
+  it('feeds resolveMediaSchedule end to end', () => {
+    const doc = toDoc(
+      '{[audio src=voice.mp3 anchor=document]}\n\n# One {duration=30}\n\n# Two {duration=20}\n\n{[audio src=a.mp3 startAt=5 clipEnd=8]}\n',
+    );
+    const sched = resolveMediaSchedule(doc);
+    const doc1 = sched.find((c) => c.anchor === 'document')!;
+    const block = sched.find((c) => c.anchor === 'block')!;
+    expect(doc1.absoluteStart).toBe(0);
+    expect(doc1.absoluteEnd).toBe(50); // spans both blocks
+    expect(block.absoluteStart).toBe(35); // block Two at 30 + startAt 5
+  });
+});

package/src/__tests__/mediaSchedule.test.ts

@@ -0,0 +1,118 @@
+import { describe, expect, it } from 'vitest';
+import { resolveMediaSchedule, getDocPlaybackDuration } from '../schemas/Media.js';
+import type { Doc, Block } from '../schemas/Doc.js';
+
+function block(partial: Partial<Block>): Block {
+  return {
+    id: partial.id ?? 'b',
+    startTime: partial.startTime ?? 0,
+    duration: partial.duration ?? 10,
+    audioSegment: 0,
+    ...partial,
+  };
+}
+
+function doc(blocks: Block[], extra?: Partial<Doc>): Doc {
+  const lastEnd = blocks.reduce((m, b) => Math.max(m, b.startTime + b.duration), 0);
+  return { articleId: 't', duration: lastEnd, blocks, audio: { segments: [] }, ...extra };
+}
+
+describe('resolveMediaSchedule', () => {
+  it('offsets a block clip by startAt relative to the block start', () => {
+    // Block #2 starts at 30s; a clip with startAt=5 plays at 35s.
+    const d = doc([
+      block({ id: 'one', startTime: 0, duration: 30 }),
+      block({
+        id: 'two',
+        startTime: 30,
+        duration: 20,
+        media: [{ id: 'm1', src: 'a.mp3', kind: 'audio', startAt: 5, clipEnd: 8, anchor: 'block' }],
+      }),
+    ]);
+    const [clip] = resolveMediaSchedule(d);
+    expect(clip.absoluteStart).toBe(35);
+    expect(clip.absoluteEnd).toBe(43); // 35 + (clipEnd 8 - clipStart 0)
+    expect(clip.sourceIn).toBe(0);
+    expect(clip.blockId).toBe('two');
+  });
+
+  it('clamps a non-spillover clip to the block end', () => {
+    const d = doc([
+      block({
+        id: 'b',
+        startTime: 0,
+        duration: 10,
+        media: [
+          { id: 'm', src: 'a.mp3', kind: 'audio', startAt: 2, clipEnd: 100, anchor: 'block' },
+        ],
+      }),
+    ]);
+    const [clip] = resolveMediaSchedule(d);
+    expect(clip.absoluteEnd).toBe(10); // clamped to block end, not 2 + 100
+  });
+
+  it('lets a spillover clip run past the block end', () => {
+    const d = doc([
+      block({
+        id: 'b',
+        startTime: 0,
+        duration: 10,
+        media: [
+          {
+            id: 'm',
+            src: 'a.mp3',
+            kind: 'audio',
+            startAt: 2,
+            clipEnd: 100,
+            spillover: true,
+            anchor: 'block',
+          },
+        ],
+      }),
+      block({ id: 'b2', startTime: 10, duration: 10 }),
+    ]);
+    const [clip] = resolveMediaSchedule(d);
+    expect(clip.absoluteEnd).toBe(102); // 2 + 100, past the block end
+  });
+
+  it('spans the whole document for an anchor=document clip', () => {
+    const d = doc([block({ id: 'b', startTime: 0, duration: 40 })], {
+      documentMedia: [
+        { id: 'narr', src: 'voice.mp3', kind: 'audio', startAt: 0, anchor: 'document' },
+      ],
+    });
+    const [clip] = resolveMediaSchedule(d);
+    expect(clip.absoluteStart).toBe(0);
+    expect(clip.absoluteEnd).toBe(40);
+    expect(clip.anchor).toBe('document');
+  });
+});
+
+describe('getDocPlaybackDuration', () => {
+  it('extends total duration to include media spillover', () => {
+    const d = doc([
+      block({
+        id: 'b',
+        startTime: 0,
+        duration: 10,
+        media: [
+          {
+            id: 'm',
+            src: 'a.mp3',
+            kind: 'audio',
+            startAt: 0,
+            clipEnd: 25,
+            spillover: true,
+            anchor: 'block',
+          },
+        ],
+      }),
+    ]);
+    expect(getDocPlaybackDuration(d)).toBe(25);
+  });
+
+  it('falls back to the block timeline when there is no media', () => {
+    const d = doc([block({ id: 'b', startTime: 0, duration: 12 })]);
+    expect(getDocPlaybackDuration(d)).toBe(12);
+  });
+});

package/src/__tests__/pandocAttrParse.test.ts

@@ -0,0 +1,187 @@
+import { describe, it, expect } from 'vitest';
+import { parseMarkdown, stringifyMarkdown } from '../markdown/index.js';
+
+function getHeading(md: string) {
+  const doc = parseMarkdown(md);
+  const heading = doc.children[0];
+  if (heading.type !== 'heading') throw new Error('expected heading');
+  return heading;
+}
+
+describe('Pandoc heading attribute parse', () => {
+  it('extracts an id-only block', () => {
+    const h = getHeading('## Section title {#intro}');
+    expect(h.attributes).toEqual({ id: 'intro' });
+    expect(h.templateAnnotation).toBeUndefined();
+  });
+
+  it('extracts classes', () => {
+    const h = getHeading('## X {.alpha .beta}');
+    expect(h.attributes?.classes).toEqual(['alpha', 'beta']);
+  });
+
+  it('extracts id + classes + params', () => {
+    const h = getHeading('## X {#abc .v1 .v2 x=400 y=200}');
+    expect(h.attributes?.id).toBe('abc');
+    expect(h.attributes?.classes).toEqual(['v1', 'v2']);
+    expect(h.attributes?.params).toEqual({ x: '400', y: '200' });
+    expect(h.attributes?.blockMeta).toEqual({ x: 400, y: 200 });
+  });
+
+  it('coerces connectsTo to a typed list', () => {
+    const h = getHeading('## X {connectsTo=foo:veryImportant,bar:requires,baz:requires}');
+    expect(h.attributes?.blockMeta?.connectsTo).toEqual([
+      { target: 'foo', type: 'veryImportant' },
+      { target: 'bar', type: 'requires' },
+      { target: 'baz', type: 'requires' },
+    ]);
+  });
+
+  it('coerces startTime/duration to seconds', () => {
+    const h = getHeading('## X {startTime=01:30 duration=00:45}');
+    expect(h.attributes?.blockMeta?.startTime).toBe(90);
+    expect(h.attributes?.blockMeta?.duration).toBe(45);
+  });
+
+  it('routes unknown keys to metadata', () => {
+    const h = getHeading('## X {#a priority=high level=info}');
+    expect(h.attributes?.metadata).toEqual({ priority: 'high', level: 'info' });
+    expect(h.attributes?.blockMeta).toBeUndefined();
+  });
+
+  it('handles quoted values with spaces', () => {
+    const h = getHeading('## X {caption="hello world"}');
+    expect(h.attributes?.params).toEqual({ caption: 'hello world' });
+    expect(h.attributes?.metadata).toEqual({ caption: 'hello world' });
+  });
+
+  it('preserves commas inside quoted values', () => {
+    const h = getHeading('## X {caption="hello, friend"}');
+    expect(h.attributes?.metadata).toEqual({ caption: 'hello, friend' });
+  });
+
+  it('escaped quotes inside quoted values', () => {
+    const h = getHeading('## X {label="he said \\"hi\\""}');
+    expect(h.attributes?.metadata?.label).toBe('he said "hi"');
+  });
+
+  it('handles single-quoted values with spaces', () => {
+    const h = getHeading("## X {caption='hello world'}");
+    expect(h.attributes?.params).toEqual({ caption: 'hello world' });
+  });
+
+  it('allows } inside a quoted value', () => {
+    const h = getHeading('## X {caption="a } b"}');
+    expect(h.attributes?.params).toEqual({ caption: 'a } b' });
+  });
+
+  it('treats an apostrophe inside an unquoted value as literal', () => {
+    const h = getHeading("## X {name=O'Brien x=4}");
+    expect(h.attributes?.metadata).toEqual({ name: "O'Brien" });
+    expect(h.attributes?.blockMeta?.x).toBe(4);
+  });
+
+  it('duplicate id: last wins', () => {
+    const h = getHeading('## X {#a #b}');
+    expect(h.attributes?.id).toBe('b');
+  });
+
+  it('duplicate key: last wins', () => {
+    const h = getHeading('## X {x=1 x=2}');
+    expect(h.attributes?.blockMeta?.x).toBe(2);
+  });
+
+  it('does NOT match a non-trailing brace block', () => {
+    const h = getHeading('## The {#wrong} section');
+    expect(h.attributes).toBeUndefined();
+  });
+
+  it('does NOT collide with {[…]} template annotation', () => {
+    const h = getHeading('## X {[chart]}');
+    expect(h.templateAnnotation).toEqual({ template: 'chart' });
+    expect(h.attributes).toBeUndefined();
+  });
+});
+
+describe('Coexistence of {#…} and {[…]}', () => {
+  it('Pandoc first, then template', () => {
+    const h = getHeading('## X {#abc} {[chart]}');
+    expect(h.attributes?.id).toBe('abc');
+    expect(h.templateAnnotation?.template).toBe('chart');
+  });
+
+  it('Template first, then Pandoc (order-agnostic)', () => {
+    const h = getHeading('## X {[chart]} {#abc}');
+    expect(h.attributes?.id).toBe('abc');
+    expect(h.templateAnnotation?.template).toBe('chart');
+  });
+
+  it('both with params on each side', () => {
+    const h = getHeading('## X {#a x=400 y=200} {[chart colorScheme=blue]}');
+    expect(h.attributes?.id).toBe('a');
+    expect(h.attributes?.blockMeta?.x).toBe(400);
+    expect(h.attributes?.blockMeta?.y).toBe(200);
+    expect(h.templateAnnotation?.template).toBe('chart');
+    expect(h.templateAnnotation?.params).toEqual({ colorScheme: 'blue' });
+  });
+
+  it('Pandoc block-meta does not leak into templateOverrides', () => {
+    const h = getHeading('## X {#a x=400} {[chart colorScheme=blue]}');
+    expect(h.templateAnnotation?.params).toEqual({ colorScheme: 'blue' });
+    expect(h.attributes?.params).toEqual({ x: '400' });
+  });
+});
+
+describe('Markdown round-trip with attributes', () => {
+  it('Pandoc-only id round-trips', () => {
+    const src = '## Section title {#intro}\n';
+    const md = parseMarkdown(src);
+    expect(stringifyMarkdown(md).trim()).toBe(src.trim());
+  });
+
+  it('canonicalizes order: Pandoc first, then template', () => {
+    const input = '## X {[chart]} {#abc}\n';
+    const md = parseMarkdown(input);
+    const out = stringifyMarkdown(md).trim();
+    expect(out).toBe('## X {#abc} {[chart]}');
+  });
+
+  it('full attribute set round-trips', () => {
+    const src =
+      '## Architecture {#arch x=600 y=300 connectsTo=foo:veryImportant,bar:requires,baz:requires} {[diagramNode]}\n';
+    const md = parseMarkdown(src);
+    const out = stringifyMarkdown(md).trim();
+    expect(out).toBe(src.trim());
+  });
+
+  it('quoted value round-trips with quoting preserved', () => {
+    const src = '## X {caption="hello world"}\n';
+    const md = parseMarkdown(src);
+    const out = stringifyMarkdown(md).trim();
+    expect(out).toBe(src.trim());
+  });
+
+  it('existing {[…]}-only docs are unchanged', () => {
+    const src = '## Getting Started {[chart colorScheme=blue]}\n';
+    const md = parseMarkdown(src);
+    const out = stringifyMarkdown(md).trim();
+    expect(out).toBe(src.trim());
+  });
+
+  it('single-quoted values canonicalize to double quotes', () => {
+    const md = parseMarkdown("## X {caption='hello world'}");
+    expect(stringifyMarkdown(md).trim()).toBe('## X {caption="hello world"}');
+  });
+
+  it('a value containing a double quote round-trips via single quotes', () => {
+    const src = '## X {label=\'say "hi"\'}';
+    const md = parseMarkdown(src);
+    expect(stringifyMarkdown(md).trim()).toBe(src);
+  });
+
+  it('a quoted } round-trips', () => {
+    const src = '## X {caption="a } b"}';
+    const md = parseMarkdown(src);
+    expect(stringifyMarkdown(md).trim()).toBe(src);
+  });
+});

package/src/__tests__/resolveDocTheme.test.ts

@@ -0,0 +1,55 @@
+/**
+ * resolveThemeForDoc — pure, doc-scoped theme resolution.
+ *
+ * The theme analog of buildRegistry: an inline custom theme resolves from the
+ * doc's own `customThemes` list, with no global `registerTheme` call. Falls
+ * back to built-ins for non-inline ids.
+ */
+
+import { describe, it, expect } from 'vitest';
+import { resolveThemeForDoc } from '../doc/resolveDocTheme';
+import { compileTheme } from '../schemas/themeCompile';
+import { DEFAULT_THEME } from '../schemas/themeLibrary';
+import type { Doc } from '../schemas/Doc.js';
+
+const brand = compileTheme({
+  id: 'my-brand',
+  name: 'My Brand',
+  seedColors: { primary: '#3182ce' },
+});
+
+function docWith(partial: Partial<Doc>): Doc {
+  return {
+    articleId: 'd',
+    duration: 0,
+    blocks: [],
+    audio: { segments: [] },
+    ...partial,
+  } as Doc;
+}
+
+describe('resolveThemeForDoc', () => {
+  it('resolves an inline custom theme doc-scoped (no global registration)', () => {
+    const doc = docWith({ customThemes: [brand], frontmatter: { 'squisq-theme': 'my-brand' } });
+    expect(resolveThemeForDoc(doc)).toEqual(brand);
+  });
+
+  it('honors an explicit id over the frontmatter selection', () => {
+    const doc = docWith({ customThemes: [brand], frontmatter: { 'squisq-theme': 'cinematic' } });
+    expect(resolveThemeForDoc(doc, 'my-brand')).toEqual(brand);
+  });
+
+  it('falls back to a built-in when the id is not an inline theme', () => {
+    const doc = docWith({ customThemes: [brand], frontmatter: { 'squisq-theme': 'cinematic' } });
+    expect(resolveThemeForDoc(doc).id).toBe('cinematic');
+  });
+
+  it('uses Doc.themeId when there is no explicit or frontmatter id', () => {
+    const doc = docWith({ customThemes: [brand], themeId: 'my-brand' });
+    expect(resolveThemeForDoc(doc)).toEqual(brand);
+  });
+
+  it('returns the default theme for a null doc', () => {
+    expect(resolveThemeForDoc(null).id).toBe(DEFAULT_THEME.id);
+  });
+});