@bendyline/squisq 1.4.1 → 1.5.0

package/src/__tests__/atmosphereLayers.test.ts

@@ -0,0 +1,108 @@
+import { describe, it, expect } from 'vitest';
+import { expandPersistentLayer } from '../doc/templates/persistentLayers.js';
+import { cssFilterForTreatment } from '../doc/utils/imageTreatment.js';
+import { themedImageTreatment } from '../doc/utils/themeUtils.js';
+import { createTemplateContext } from '../schemas/BlockTemplates.js';
+import { DEFAULT_THEME, resolveTheme } from '../schemas/themeLibrary.js';
+import { validateTheme } from '../schemas/themeValidator.js';
+import { THEMES } from '../schemas/themeLibrary.js';
+import type { ShapeLayer, ImageLayer } from '../schemas/Doc.js';
+
+describe('atmosphere persistent layers', () => {
+  it('patternBackground expands dots/grid/diagonal to an SVG pattern fill', () => {
+    const [layer] = expandPersistentLayer({
+      template: 'patternBackground',
+      config: { type: 'patternBackground', pattern: 'grid', color: '#00e5ff', opacity: 0.04 },
+    }) as ShapeLayer[];
+    expect(layer.type).toBe('shape');
+    expect(layer.content.pattern).toEqual({
+      kind: 'grid',
+      color: '#00e5ff',
+      size: 24,
+      opacity: 0.04,
+    });
+  });
+
+  it('patternBackground noise expands to a grain filter rect', () => {
+    const [layer] = expandPersistentLayer({
+      template: 'patternBackground',
+      config: { type: 'patternBackground', pattern: 'noise', opacity: 0.05 },
+    }) as ShapeLayer[];
+    expect(layer.content.filter).toEqual({ type: 'noise', opacity: 0.05 });
+  });
+
+  it('vignette expands to a radial gradient rect with strength-scaled edge', () => {
+    const [layer] = expandPersistentLayer({
+      template: 'vignette',
+      config: { type: 'vignette', strength: 0.4 },
+    }) as ShapeLayer[];
+    expect(layer.content.fill).toContain('radial-gradient');
+    expect(layer.content.fill).toContain('rgba(0, 0, 0, 0.4)');
+  });
+
+  it('ambientGradient derives colors from the theme and drifts slowly', () => {
+    const theme = resolveTheme('gezellig');
+    const [layer] = expandPersistentLayer(
+      { template: 'ambientGradient', config: { type: 'ambientGradient' } },
+      theme,
+    ) as ShapeLayer[];
+    expect(layer.content.fill).toContain(theme.colors.backgroundLight);
+    expect(layer.animation?.type).toBe('slowZoom');
+    expect(layer.animation?.duration).toBe(40);
+    // Oversized so the pan never reveals the frame edge
+    expect(layer.position.width).toBe('110%');
+  });
+
+  it('imageBackground passes blur through to the image layer', () => {
+    const [image] = expandPersistentLayer({
+      template: 'imageBackground',
+      config: { type: 'imageBackground', src: 'bg.jpg', blur: 12 },
+    }) as ImageLayer[];
+    expect(image.content.blur).toBe(12);
+  });
+
+  it('every built-in theme still validates with its atmosphere layers', () => {
+    for (const [id, theme] of Object.entries(THEMES)) {
+      const result = validateTheme(theme);
+      expect(result.valid, `theme ${id}: ${JSON.stringify(result.errors)}`).toBe(true);
+    }
+  });
+});
+
+describe('image treatments', () => {
+  it('mono produces a grayscale filter scaled by strength', () => {
+    expect(cssFilterForTreatment({ type: 'mono', strength: 1 })).toContain('grayscale(1)');
+    expect(cssFilterForTreatment({ type: 'mono', strength: 0.5 })).toContain('grayscale(0.5)');
+  });
+
+  it('duotone rotates hue toward the tint color', () => {
+    // #ff0000 has hue 0 → rotation 0 - 40 = -40deg
+    const f = cssFilterForTreatment({ type: 'duotone', color: '#ff0000' });
+    expect(f).toContain('grayscale(1)');
+    expect(f).toContain('hue-rotate(-40deg)');
+  });
+
+  it('none / absent treatments produce no filter', () => {
+    expect(cssFilterForTreatment({ type: 'none' })).toBeUndefined();
+    expect(cssFilterForTreatment(undefined)).toBeUndefined();
+  });
+
+  it('blur composes with (or without) a treatment', () => {
+    expect(cssFilterForTreatment(undefined, 12)).toBe('blur(12px)');
+    expect(cssFilterForTreatment({ type: 'mono' }, 8)).toMatch(/^blur\(8px\) grayscale/);
+  });
+
+  it('themedImageTreatment: block override wins, none opts out, duotone tints from primary', () => {
+    const documentary = resolveTheme('documentary');
+    const ctx = createTemplateContext(documentary, 0, 1);
+    // Theme authors mono
+    expect(themedImageTreatment(ctx)?.type).toBe('mono');
+    // Block opts out
+    expect(themedImageTreatment(ctx, 'none')).toBeUndefined();
+    // Block forces duotone → tint defaults to theme primary
+    expect(themedImageTreatment(ctx, 'duotone')?.color).toBe(documentary.colors.primary);
+    // Standard theme has no treatment
+    const plainCtx = createTemplateContext(DEFAULT_THEME, 0, 1);
+    expect(themedImageTreatment(plainCtx)).toBeUndefined();
+  });
+});

package/src/__tests__/attrTokens.test.ts

@@ -0,0 +1,162 @@
+import { describe, it, expect } from 'vitest';
+import {
+  tokenizeAttrTokens,
+  splitKeyValueToken,
+  unquoteAttrValue,
+  needsQuoting,
+  quoteAttrValue,
+  matchTrailingTemplateAnnotation,
+  matchTrailingPandocAttr,
+} from '../markdown/attrTokens.js';
+
+describe('tokenizeAttrTokens', () => {
+  it('splits bare tokens on whitespace', () => {
+    expect(tokenizeAttrTokens('chart colorScheme=blue size=large')).toEqual([
+      'chart',
+      'colorScheme=blue',
+      'size=large',
+    ]);
+  });
+
+  it('keeps a double-quoted value as one token', () => {
+    expect(tokenizeAttrTokens('caption="Beach at sunset" columns=3')).toEqual([
+      'caption="Beach at sunset"',
+      'columns=3',
+    ]);
+  });
+
+  it('keeps a single-quoted value as one token', () => {
+    expect(tokenizeAttrTokens("caption='Beach at sunset'")).toEqual(["caption='Beach at sunset'"]);
+  });
+
+  it('treats a quote mid-value as a literal character', () => {
+    // The quote in O'Brien is not at a value start, so it must not open a
+    // quoted run and swallow the following token.
+    expect(tokenizeAttrTokens("attribution=O'Brien x=4")).toEqual(["attribution=O'Brien", 'x=4']);
+  });
+
+  it('preserves escape pairs inside a quoted run', () => {
+    expect(tokenizeAttrTokens('label="he said \\"hi\\""')).toEqual(['label="he said \\"hi\\""']);
+  });
+
+  it('tolerates an unbalanced opening quote (run extends to end of input)', () => {
+    expect(tokenizeAttrTokens('caption="oops trailing')).toEqual(['caption="oops trailing']);
+  });
+
+  it('keeps a bare quoted token verbatim', () => {
+    expect(tokenizeAttrTokens('"just a string"')).toEqual(['"just a string"']);
+  });
+});
+
+describe('splitKeyValueToken / unquoteAttrValue', () => {
+  it('splits on the first =', () => {
+    expect(splitKeyValueToken('a=b=c')).toEqual({ key: 'a', value: 'b=c' });
+  });
+
+  it('returns null for tokens without = past the first character', () => {
+    expect(splitKeyValueToken('chart')).toBeNull();
+    expect(splitKeyValueToken('#id')).toBeNull();
+    expect(splitKeyValueToken('=leading')).toBeNull();
+  });
+
+  it('strips matching double quotes and unescapes', () => {
+    expect(splitKeyValueToken('label="he said \\"hi\\""')).toEqual({
+      key: 'label',
+      value: 'he said "hi"',
+    });
+  });
+
+  it('strips matching single quotes and unescapes', () => {
+    expect(splitKeyValueToken("label='it\\'s here'")).toEqual({ key: 'label', value: "it's here" });
+  });
+
+  it('leaves unmatched quotes verbatim', () => {
+    expect(unquoteAttrValue('"unbalanced')).toBe('"unbalanced');
+    expect(unquoteAttrValue('"')).toBe('"');
+  });
+
+  it('leaves backslashes before other characters alone', () => {
+    expect(unquoteAttrValue('"C:\\temp"')).toBe('C:\\temp');
+  });
+});
+
+describe('needsQuoting / quoteAttrValue', () => {
+  it('passes simple values through bare', () => {
+    expect(quoteAttrValue('blue')).toBe('blue');
+    expect(quoteAttrValue('a,b,c')).toBe('a,b,c');
+    expect(quoteAttrValue('foo:flow')).toBe('foo:flow');
+  });
+
+  it('double-quotes values with spaces', () => {
+    expect(quoteAttrValue('Beach at sunset')).toBe('"Beach at sunset"');
+  });
+
+  it('quotes empty values', () => {
+    expect(quoteAttrValue('')).toBe('""');
+  });
+
+  it('quotes values containing brackets or braces', () => {
+    expect(needsQuoting('a]b')).toBe(true);
+    expect(quoteAttrValue('a]b')).toBe('"a]b"');
+    expect(quoteAttrValue('a}b')).toBe('"a}b"');
+  });
+
+  it('switches to single quotes when the value contains a double quote', () => {
+    expect(quoteAttrValue('She said "hi"')).toBe('\'She said "hi"\'');
+  });
+
+  it('falls back to double quotes with escapes when both quote chars appear', () => {
+    expect(quoteAttrValue('it\'s a "thing"')).toBe('"it\'s a \\"thing\\""');
+  });
+
+  it('round-trips through tokenize + split', () => {
+    const values = ['Beach at sunset', 'a ] b', 'She said "hi"', "it's fine", 'C:\\temp', ''];
+    for (const value of values) {
+      const tokens = tokenizeAttrTokens(`key=${quoteAttrValue(value)}`);
+      expect(tokens).toHaveLength(1);
+      expect(splitKeyValueToken(tokens[0])).toEqual({ key: 'key', value });
+    }
+  });
+});
+
+describe('matchTrailingTemplateAnnotation', () => {
+  it('matches a simple trailing annotation', () => {
+    const m = matchTrailingTemplateAnnotation('Getting Started {[comparisonBar]}');
+    expect(m?.inner).toBe('comparisonBar');
+  });
+
+  it('allows ] inside a quoted value', () => {
+    const m = matchTrailingTemplateAnnotation('X {[quote text="a ] b"]}');
+    expect(m?.inner).toBe('quote text="a ] b"');
+  });
+
+  it('falls back to the legacy grammar for unbalanced quotes', () => {
+    const m = matchTrailingTemplateAnnotation('X {[quote text="oops]}');
+    expect(m?.inner).toBe('quote text="oops');
+  });
+
+  it('still tolerates an accidentally doubled trailing ]}', () => {
+    const m = matchTrailingTemplateAnnotation('X {[comparisonBar]}]}');
+    expect(m?.inner).toBe('comparisonBar');
+  });
+
+  it('rejects non-trailing annotations', () => {
+    expect(matchTrailingTemplateAnnotation('The {[chart]} section')).toBeNull();
+  });
+});
+
+describe('matchTrailingPandocAttr', () => {
+  it('matches a simple trailing block', () => {
+    const m = matchTrailingPandocAttr('Section {#intro .wide x=4}');
+    expect(m?.inner).toBe('#intro .wide x=4');
+  });
+
+  it('allows } inside a quoted value', () => {
+    const m = matchTrailingPandocAttr('X {caption="a } b"}');
+    expect(m?.inner).toBe('caption="a } b"');
+  });
+
+  it('does not match the {[…]} template form', () => {
+    expect(matchTrailingPandocAttr('X {[chart]}')).toBeNull();
+  });
+});

package/src/__tests__/customTemplateSample.test.ts

@@ -0,0 +1,83 @@
+/**
+ * End-to-end sanity check: the kind of doc a user might compose by
+ * hand (or via the upcoming TemplateDesigner) renders through the
+ * markdown → Doc → expanded layers pipeline with tokens substituted.
+ *
+ * Build-the-payload-here so the test doesn't depend on the site
+ * package — it's verifying the pure pipeline.
+ */
+
+import { describe, it, expect } from 'vitest';
+import { markdownToDoc } from '../doc/markdownToDoc';
+import { expandDocBlocks } from '../doc/templates/index';
+import { parseMarkdown } from '../markdown/parse';
+import { writeCustomTemplatesToFrontmatter } from '../doc/customTemplatesFrontmatter';
+import type { CustomTemplateDefinition } from '../schemas/CustomTemplates.js';
+import type { TextLayer } from '../schemas/Doc.js';
+import { VIEWPORT_PRESETS } from '../schemas/Viewport.js';
+
+const heroDef: CustomTemplateDefinition = {
+  name: 'hero',
+  label: 'Hero Section',
+  viewport: { width: 1920, height: 1080 },
+  layers: [
+    {
+      id: 'hero-title',
+      type: 'text',
+      position: { x: '6%', y: '20%', width: '88%' },
+      content: {
+        text: '{title}',
+        style: { fontSize: 96, color: '#0f172a' },
+      },
+    },
+    {
+      id: 'hero-body',
+      type: 'text',
+      position: { x: '6%', y: '52%', width: '88%' },
+      content: {
+        text: '{content}',
+        style: { fontSize: 36, color: '#475569' },
+      },
+    },
+  ],
+};
+
+function buildSampleMarkdown(): string {
+  const payload = writeCustomTemplatesToFrontmatter([heroDef]);
+  return `---
+squisq-custom-templates: "${payload}"
+---
+
+# Welcome to Squisq {[hero]}
+
+A small editor for big ideas.
+`;
+}
+
+describe('Custom template pipeline (markdown → expanded layers)', () => {
+  it('substitutes {title} and {content} when a doc uses a frontmatter-defined template', () => {
+    const doc = markdownToDoc(parseMarkdown(buildSampleMarkdown()));
+    const blocks = expandDocBlocks(doc.blocks, {
+      customTemplates: doc.customTemplates,
+    });
+    expect(blocks).toHaveLength(1);
+    const layers = blocks[0].layers ?? [];
+    expect(layers).toHaveLength(2);
+
+    expect((layers[0] as TextLayer).content.text).toBe('Welcome to Squisq');
+    expect((layers[1] as TextLayer).content.text).toBe('A small editor for big ideas.');
+  });
+
+  it('renders the same template against a portrait viewport without re-authoring', () => {
+    const doc = markdownToDoc(parseMarkdown(buildSampleMarkdown()));
+    const blocks = expandDocBlocks(doc.blocks, {
+      customTemplates: doc.customTemplates,
+      viewport: VIEWPORT_PRESETS.portrait,
+    });
+    const layers = blocks[0].layers ?? [];
+    // %-based positions survive the viewport switch — the SSR
+    // renderer resolves them against the actual viewport at draw time.
+    expect(layers[0].position.x).toBe('6%');
+    expect(layers[0].position.width).toBe('88%');
+  });
+});

package/src/__tests__/customTemplatesFrontmatter.test.ts

@@ -0,0 +1,205 @@
+/**
+ * Custom templates round-trip through frontmatter.
+ *
+ * Verifies that a CustomTemplateDefinition stored in markdown
+ * frontmatter is faithfully reconstructed by `markdownToDoc` and
+ * serialized back by `docToMarkdown` without loss.
+ */
+
+import { describe, it, expect, vi } from 'vitest';
+import { markdownToDoc } from '../doc/markdownToDoc';
+import { docToMarkdown } from '../doc/docToMarkdown';
+import {
+  encodeLayersForFrontmatter,
+  decodeLayersFromFrontmatter,
+  readCustomTemplatesFromFrontmatter,
+  writeCustomTemplatesToFrontmatter,
+  FRONTMATTER_CUSTOM_TEMPLATES_KEY,
+} from '../doc/customTemplatesFrontmatter';
+import { parseMarkdown } from '../markdown/parse';
+import type { Layer } from '../schemas/Doc.js';
+import type { CustomTemplateDefinition } from '../schemas/CustomTemplates.js';
+
+const sampleLayers: Layer[] = [
+  {
+    id: 'title',
+    type: 'text',
+    position: { x: '5%', y: '10%', width: '90%' },
+    content: { text: '{title}', style: { fontSize: 72, color: '#000' } },
+  },
+  {
+    id: 'body',
+    type: 'text',
+    position: { x: '5%', y: '40%', width: '90%' },
+    content: { text: '{content}', style: { fontSize: 32, color: '#333' } },
+  },
+];
+
+const heroDef: CustomTemplateDefinition = {
+  name: 'hero',
+  label: 'Hero',
+  description: 'Large title with body below.',
+  viewport: { width: 1920, height: 1080 },
+  layers: sampleLayers,
+};
+
+describe('encodeLayersForFrontmatter ↔ decodeLayersFromFrontmatter', () => {
+  it('round-trips a single Layer array verbatim', () => {
+    const encoded = encodeLayersForFrontmatter(sampleLayers);
+    const decoded = decodeLayersFromFrontmatter(encoded);
+    expect(decoded).toEqual(sampleLayers);
+  });
+
+  it("returns [] when the base64 isn't valid JSON", () => {
+    const garbage = encodeLayersForFrontmatter(sampleLayers).slice(0, 4);
+    expect(decodeLayersFromFrontmatter(garbage)).toEqual([]);
+  });
+});
+
+describe('writeCustomTemplatesToFrontmatter → readCustomTemplatesFromFrontmatter', () => {
+  it('round-trips a single definition through the compact JSON wire format', () => {
+    const payload = writeCustomTemplatesToFrontmatter([heroDef]);
+    expect(typeof payload).toBe('string');
+    // Compact form: a readable JSON object keyed by name, short keys, no
+    // base64, and the default 1920×1080 viewport omitted.
+    expect(payload!.startsWith('{"hero":')).toBe(true);
+    expect(payload).toContain('"lb":"Hero"');
+    expect(payload).not.toContain('"viewport"');
+    const fm = { [FRONTMATTER_CUSTOM_TEMPLATES_KEY]: payload };
+    const out = readCustomTemplatesFromFrontmatter(fm);
+    expect(out).toHaveLength(1);
+    expect(out![0]).toEqual(heroDef);
+  });
+
+  it('is markedly smaller than the legacy base64 form', () => {
+    const compact = writeCustomTemplatesToFrontmatter([heroDef])!;
+    const legacyBase64 = btoa(unescape(encodeURIComponent(JSON.stringify([{ ...heroDef }]))));
+    expect(compact.length).toBeLessThan(legacyBase64.length);
+  });
+
+  it('still reads the legacy base64-JSON payload (back-compat)', () => {
+    // What older documents have on disk: base64 of the full-keyed array.
+    const legacy = btoa(unescape(encodeURIComponent(JSON.stringify([heroDef]))));
+    const out = readCustomTemplatesFromFrontmatter({
+      [FRONTMATTER_CUSTOM_TEMPLATES_KEY]: legacy,
+    });
+    expect(out).toHaveLength(1);
+    expect(out![0]).toEqual(heroDef);
+  });
+
+  it('round-trips layers carrying the full styling field set without loss', () => {
+    const rich: CustomTemplateDefinition = {
+      name: 'rich',
+      label: 'Rich',
+      viewport: { width: 1080, height: 1080 },
+      layers: [
+        {
+          id: 'p',
+          type: 'path',
+          position: { x: '1%', y: '2%', width: '3%', height: '4%', anchor: 'center' },
+          content: {
+            d: 'M0 0',
+            shapeKind: 'star',
+            fill: '#fff',
+            fillOpacity: 0.5,
+            gradient: { from: '#000', to: '#fff', angle: 90 },
+            stroke: '#111',
+            strokeWidth: 3,
+            borderStyle: 'dashed',
+            dasharray: '4 2',
+          },
+        } as Layer,
+      ],
+    };
+    const payload = writeCustomTemplatesToFrontmatter([rich])!;
+    const out = readCustomTemplatesFromFrontmatter({ [FRONTMATTER_CUSTOM_TEMPLATES_KEY]: payload });
+    expect(out![0]).toEqual(rich);
+  });
+
+  it('round-trips multiple definitions in declaration order', () => {
+    const second: CustomTemplateDefinition = { ...heroDef, name: 'second', label: 'Second' };
+    const payload = writeCustomTemplatesToFrontmatter([heroDef, second]);
+    const out = readCustomTemplatesFromFrontmatter({
+      [FRONTMATTER_CUSTOM_TEMPLATES_KEY]: payload,
+    });
+    expect(out!.map((d) => d.name)).toEqual(['hero', 'second']);
+  });
+
+  it('also accepts an already-decoded array shape (forward-compatible)', () => {
+    const out = readCustomTemplatesFromFrontmatter({
+      [FRONTMATTER_CUSTOM_TEMPLATES_KEY]: [
+        {
+          name: 'hero',
+          label: 'Hero',
+          viewport: { width: 1920, height: 1080 },
+          layers: sampleLayers,
+        },
+      ],
+    });
+    expect(out).toHaveLength(1);
+    expect(out![0].name).toBe('hero');
+  });
+
+  it('returns undefined when the key is absent', () => {
+    expect(readCustomTemplatesFromFrontmatter({})).toBeUndefined();
+    expect(readCustomTemplatesFromFrontmatter(undefined)).toBeUndefined();
+  });
+
+  it("returns undefined when the encoded string isn't a valid array", () => {
+    const fm = { [FRONTMATTER_CUSTOM_TEMPLATES_KEY]: 'not-base64-of-an-array' };
+    expect(readCustomTemplatesFromFrontmatter(fm)).toBeUndefined();
+  });
+});
+
+describe('Doc.customTemplates round-trip via markdownToDoc + docToMarkdown', () => {
+  it('survives a markdownToDoc → docToMarkdown cycle', () => {
+    const encoded = writeCustomTemplatesToFrontmatter([heroDef])!;
+    // Compact JSON is stored unquoted — it round-trips verbatim through
+    // the line-based frontmatter parser.
+    const sourceMd = `---
+title: My Doc
+squisq-custom-templates: ${encoded}
+---
+
+# Welcome {[hero]}
+
+A small editor for big ideas.
+`;
+    const doc = markdownToDoc(parseMarkdown(sourceMd));
+    expect(doc.customTemplates).toBeDefined();
+    expect(doc.customTemplates).toHaveLength(1);
+    expect(doc.customTemplates![0].name).toBe('hero');
+    expect(doc.customTemplates![0].layers).toEqual(sampleLayers);
+
+    // Round-trip back — docToMarkdown must restore the frontmatter
+    // entry with an equivalent encoded payload.
+    const mdOut = docToMarkdown(doc);
+    expect(mdOut.frontmatter).toBeDefined();
+    const payload = mdOut.frontmatter![FRONTMATTER_CUSTOM_TEMPLATES_KEY];
+    expect(typeof payload).toBe('string');
+    const reread = readCustomTemplatesFromFrontmatter({
+      [FRONTMATTER_CUSTOM_TEMPLATES_KEY]: payload,
+    });
+    expect(reread).toEqual(doc.customTemplates);
+  });
+
+  it('drops the frontmatter key when the doc has no custom templates anymore', () => {
+    void vi; // imported for parity; not used here
+    const doc = {
+      articleId: 'd',
+      duration: 0,
+      blocks: [],
+      audio: { segments: [] },
+      // Stale frontmatter from an earlier save when the doc DID have
+      // custom templates — but doc.customTemplates is now empty.
+      frontmatter: {
+        title: 'Doc',
+        [FRONTMATTER_CUSTOM_TEMPLATES_KEY]: 'stale-base64-blob',
+      },
+    };
+    const md = docToMarkdown(doc);
+    expect(md.frontmatter).toBeDefined();
+    expect(md.frontmatter).not.toHaveProperty(FRONTMATTER_CUSTOM_TEMPLATES_KEY);
+    expect(md.frontmatter!.title).toBe('Doc');
+  });
+});

package/src/__tests__/customThemesFrontmatter.test.ts

@@ -0,0 +1,118 @@
+/**
+ * Custom themes round-trip through frontmatter.
+ *
+ * The theme analog of customTemplatesFrontmatter.test.ts: verifies that a
+ * Theme stored in markdown frontmatter under `squisq-custom-themes` is
+ * faithfully reconstructed by `markdownToDoc` and serialized back by
+ * `docToMarkdown` without loss, and that the reader is tolerant of malformed
+ * entries.
+ */
+
+import { describe, it, expect } from 'vitest';
+import { markdownToDoc } from '../doc/markdownToDoc';
+import { docToMarkdown } from '../doc/docToMarkdown';
+import {
+  readCustomThemesFromFrontmatter,
+  writeCustomThemesToFrontmatter,
+  FRONTMATTER_CUSTOM_THEMES_KEY,
+} from '../doc/customThemesFrontmatter';
+import { parseMarkdown } from '../markdown/parse';
+import { compileTheme } from '../schemas/themeCompile';
+import type { Doc } from '../schemas/Doc.js';
+import type { Theme } from '../schemas/Theme.js';
+
+const brand: Theme = compileTheme({
+  id: 'my-brand',
+  name: 'My Brand',
+  seedColors: { primary: '#3182ce', secondary: '#805ad5' },
+});
+
+describe('writeCustomThemesToFrontmatter → readCustomThemesFromFrontmatter', () => {
+  it('round-trips a single theme through the compact JSON wire format', () => {
+    const payload = writeCustomThemesToFrontmatter([brand]);
+    expect(typeof payload).toBe('string');
+    expect(payload!.startsWith('{"my-brand":')).toBe(true);
+    const out = readCustomThemesFromFrontmatter({ [FRONTMATTER_CUSTOM_THEMES_KEY]: payload });
+    expect(out).toHaveLength(1);
+    expect(out![0]).toEqual(brand);
+  });
+
+  it('round-trips multiple themes keyed by id', () => {
+    const second = compileTheme({
+      id: 'second',
+      name: 'Second',
+      seedColors: { primary: '#e53e3e' },
+    });
+    const payload = writeCustomThemesToFrontmatter([brand, second]);
+    const out = readCustomThemesFromFrontmatter({ [FRONTMATTER_CUSTOM_THEMES_KEY]: payload });
+    expect(out!.map((t) => t.id).sort()).toEqual(['my-brand', 'second']);
+  });
+
+  it('also accepts an already-decoded object map (forward-compatible)', () => {
+    const out = readCustomThemesFromFrontmatter({
+      [FRONTMATTER_CUSTOM_THEMES_KEY]: { 'my-brand': brand },
+    });
+    expect(out).toHaveLength(1);
+    expect(out![0].id).toBe('my-brand');
+  });
+
+  it('drops invalid themes rather than failing the whole load', () => {
+    const payload = JSON.stringify({ 'my-brand': brand, junk: { id: 'junk' } });
+    const out = readCustomThemesFromFrontmatter({ [FRONTMATTER_CUSTOM_THEMES_KEY]: payload });
+    expect(out).toHaveLength(1);
+    expect(out![0].id).toBe('my-brand');
+  });
+
+  it('returns undefined when the key is absent or unparseable', () => {
+    expect(readCustomThemesFromFrontmatter({})).toBeUndefined();
+    expect(readCustomThemesFromFrontmatter(undefined)).toBeUndefined();
+    expect(
+      readCustomThemesFromFrontmatter({ [FRONTMATTER_CUSTOM_THEMES_KEY]: 'not json' }),
+    ).toBeUndefined();
+  });
+});
+
+describe('Doc.customThemes round-trip via markdownToDoc + docToMarkdown', () => {
+  it('survives a markdownToDoc → docToMarkdown cycle and keeps the selection', () => {
+    const encoded = writeCustomThemesToFrontmatter([brand])!;
+    // Compact JSON is stored unquoted — it round-trips verbatim through the
+    // line-based frontmatter parser, exactly like custom templates.
+    const sourceMd = `---
+title: My Doc
+squisq-theme: my-brand
+squisq-custom-themes: ${encoded}
+---
+
+# Welcome
+
+A small editor for big ideas.
+`;
+    const doc = markdownToDoc(parseMarkdown(sourceMd));
+    expect(doc.customThemes).toHaveLength(1);
+    expect(doc.customThemes![0]).toEqual(brand);
+
+    const mdOut = docToMarkdown(doc);
+    const payload = mdOut.frontmatter![FRONTMATTER_CUSTOM_THEMES_KEY];
+    expect(typeof payload).toBe('string');
+    const reread = readCustomThemesFromFrontmatter({ [FRONTMATTER_CUSTOM_THEMES_KEY]: payload });
+    expect(reread).toEqual(doc.customThemes);
+    // The active selection is preserved untouched.
+    expect(mdOut.frontmatter!['squisq-theme']).toBe('my-brand');
+  });
+
+  it('drops the frontmatter key when the doc has no custom themes anymore', () => {
+    const doc: Doc = {
+      articleId: 'd',
+      duration: 0,
+      blocks: [],
+      audio: { segments: [] },
+      frontmatter: {
+        title: 'Doc',
+        [FRONTMATTER_CUSTOM_THEMES_KEY]: 'stale-blob',
+      },
+    };
+    const md = docToMarkdown(doc);
+    expect(md.frontmatter).not.toHaveProperty(FRONTMATTER_CUSTOM_THEMES_KEY);
+    expect(md.frontmatter!.title).toBe('Doc');
+  });
+});