@bendyline/squisq 1.5.2 → 2.0.0

package/src/__tests__/getLayers.test.ts

@@ -1,5 +1,6 @@
 import { describe, it, expect, vi } from 'vitest';
-import { getLayers, RenderContext } from '../doc/getLayers.js';
+import type { MaterializeBlockLayersOptions } from '../doc/materializeBlockLayers.js';
+import { materializeLayers } from './materializeTestUtils.js';
 import { DEFAULT_THEME } from '../schemas/themeLibrary.js';
 import { TemplateBlock, PersistentLayerConfig } from '../schemas/BlockTemplates.js';
 import { VIEWPORT_PRESETS } from '../schemas/Viewport.js';
@@ -30,7 +31,7 @@ function makeRawBlock(layers: Layer[]): Block {
   };
 }
 
-const defaultContext: RenderContext = {
+const defaultContext: MaterializeBlockLayersOptions = {
   theme: DEFAULT_THEME,
   viewport: VIEWPORT_PRESETS.landscape,
   blockIndex: 0,
@@ -41,10 +42,10 @@ const defaultContext: RenderContext = {
 // Tests
 // ---------------------------------------------------------------------------
 
-describe('getLayers', () => {
+describe('materializeBlockLayers', () => {
   it('generates layers for a known template block', () => {
     const block = makeTemplateBlock({ template: 'title', title: 'Test Title' });
-    const layers = getLayers(block, defaultContext);
+    const layers = materializeLayers(block, defaultContext);
 
     expect(Array.isArray(layers)).toBe(true);
     expect(layers.length).toBeGreaterThan(0);
@@ -61,7 +62,7 @@ describe('getLayers', () => {
       stat: '42%',
       description: 'of users',
     });
-    const layers = getLayers(block, defaultContext);
+    const layers = materializeLayers(block, defaultContext);
 
     expect(layers.length).toBeGreaterThan(0);
     const texts = layers.filter((l) => l.type === 'text');
@@ -78,13 +79,17 @@ describe('getLayers', () => {
       } as ShapeLayer,
     ];
     const block = makeRawBlock(existingLayers);
-    const layers = getLayers(block, defaultContext);
+    const layers = materializeLayers(block, defaultContext);
 
     expect(layers).toEqual(existingLayers);
+    expect(layers).not.toBe(existingLayers);
+    expect(layers[0]).not.toBe(existingLayers[0]);
+    (layers[0] as ShapeLayer).content.fill = '#000000';
+    expect((existingLayers[0] as ShapeLayer).content.fill).toBe('#ff0000');
   });
 
   it('resolves legacy template aliases through TEMPLATE_ALIASES', () => {
-    // Regression: `getLayers` previously did `block.template in templateRegistry`
+    // Regression: the old resolver used `block.template in templateRegistry`
     // without alias resolution, so docs authored with the legacy long ids
     // (`titleBlock`, `quoteBlock`, `mapBlock`, `listBlock`) rendered as
     // empty SVG cards in the linear/document view — `hasTemplate()` accepts
@@ -103,7 +108,7 @@ describe('getLayers', () => {
         items: ['a', 'b', 'c'],
         quote: 'q',
       } as Partial<TemplateBlock>);
-      const layers = getLayers(block, defaultContext);
+      const layers = materializeLayers(block, defaultContext);
       expect(layers.length).toBeGreaterThan(0);
     }
   });
@@ -115,7 +120,7 @@ describe('getLayers', () => {
       duration: 5,
       audioSegment: 0,
     } as unknown as TemplateBlock;
-    const layers = getLayers(block, defaultContext);
+    const layers = materializeLayers(block, defaultContext);
 
     expect(layers.length).toBeGreaterThan(0);
     const noticeText = layers
@@ -126,14 +131,14 @@ describe('getLayers', () => {
 
   it('returns empty array for block with no template and no layers', () => {
     const block: Block = { id: 'empty-1', duration: 5, startTime: 0, audioSegment: 0 };
-    const layers = getLayers(block, defaultContext);
+    const layers = materializeLayers(block, defaultContext);
 
     expect(layers).toEqual([]);
   });
 
   it('uses default context values when context is omitted', () => {
     const block = makeTemplateBlock({ template: 'title', title: 'Defaults' });
-    const layers = getLayers(block);
+    const layers = materializeLayers(block);
 
     expect(Array.isArray(layers)).toBe(true);
     expect(layers.length).toBeGreaterThan(0);
@@ -144,12 +149,12 @@ describe('getLayers', () => {
     const consoleSpy = vi.spyOn(console, 'error').mockImplementation(() => {});
 
     // comparisonBar requires numeric values; passing invalid data may throw
-    // but getLayers should catch and return []
+    // but materialization should degrade without throwing
     const block = makeTemplateBlock({
       template: 'comparisonBar',
       // Missing required fields
     });
-    const layers = getLayers(block, defaultContext);
+    const layers = materializeLayers(block, defaultContext);
 
     expect(Array.isArray(layers)).toBe(true);
     consoleSpy.mockRestore();
@@ -177,7 +182,10 @@ describe('getLayers', () => {
 
     it('injects persistent bottom and top layers around block layers', () => {
       const block = makeTemplateBlock({ template: 'title', title: 'With Persistent' });
-      const layers = getLayers(block, { ...defaultContext, persistentLayers: persistentConfig });
+      const layers = materializeLayers(block, {
+        ...defaultContext,
+        persistentLayers: persistentConfig,
+      });
 
       // First layer should be the bottom persistent layer
       expect(layers[0]).toEqual(bottomLayer);
@@ -193,7 +201,10 @@ describe('getLayers', () => {
         title: 'No Bottom',
         useBottomLayer: false,
       });
-      const layers = getLayers(block, { ...defaultContext, persistentLayers: persistentConfig });
+      const layers = materializeLayers(block, {
+        ...defaultContext,
+        persistentLayers: persistentConfig,
+      });
 
       // Should NOT start with the bottom persistent layer
       expect(layers[0]).not.toEqual(bottomLayer);
@@ -207,7 +218,10 @@ describe('getLayers', () => {
         title: 'No Top',
         useTopLayer: false,
       });
-      const layers = getLayers(block, { ...defaultContext, persistentLayers: persistentConfig });
+      const layers = materializeLayers(block, {
+        ...defaultContext,
+        persistentLayers: persistentConfig,
+      });
 
       // Should start with the bottom persistent layer
       expect(layers[0]).toEqual(bottomLayer);
@@ -217,8 +231,8 @@ describe('getLayers', () => {
 
     it('skips injection when no persistent layers are configured', () => {
       const block = makeTemplateBlock({ template: 'title', title: 'No Persistent' });
-      const withoutPersistent = getLayers(block, defaultContext);
-      const withEmptyPersistent = getLayers(block, {
+      const withoutPersistent = materializeLayers(block, defaultContext);
+      const withEmptyPersistent = materializeLayers(block, {
         ...defaultContext,
         persistentLayers: { bottomLayers: [], topLayers: [] },
       });

package/src/__tests__/getLayersFallback.test.ts

@@ -1,7 +1,7 @@
 import { describe, it, expect, afterEach } from 'vitest';
 import { parseMarkdown } from '../markdown/parse.js';
 import { markdownToDoc } from '../doc/markdownToDoc.js';
-import { getLayers } from '../doc/getLayers.js';
+import { materializeLayers } from './materializeTestUtils.js';
 import { templateRegistry } from '../doc/templates/index.js';
 import type { Block, Layer } from '../schemas/Doc.js';
 
@@ -15,10 +15,10 @@ function firstBlock(md: string): Block {
   return markdownToDoc(parseMarkdown(md)).blocks[0];
 }
 
-describe('getLayers — graceful degradation', () => {
+describe('materializeBlockLayers — graceful degradation', () => {
   it('renders an unknown template as a plain card with title, body, and notice', () => {
     const block = firstBlock('## My Section {[photGrid]}\n\nSome body prose here.');
-    const layers = getLayers(block);
+    const layers = materializeLayers(block);
     expect(layers.length).toBeGreaterThan(0);
     const text = textOf(layers);
     expect(text).toContain('My Section');
@@ -39,7 +39,7 @@ describe('getLayers — graceful degradation', () => {
         template: '__boom',
         title: 'Exploding block',
       };
-      const layers = getLayers(block);
+      const layers = materializeLayers(block);
       expect(layers.length).toBeGreaterThan(0);
       expect(textOf(layers)).toContain('Template "__boom" failed');
       expect(textOf(layers)).toContain('Exploding block');
@@ -50,11 +50,11 @@ describe('getLayers — graceful degradation', () => {
 
   it('blocks with no template at all still return empty layers', () => {
     const block: Block = { id: 'raw', startTime: 0, duration: 5, audioSegment: 0 };
-    expect(getLayers(block)).toEqual([]);
+    expect(materializeLayers(block)).toEqual([]);
   });
 });
 
-describe('getLayers — structured data feeds templates', () => {
+describe('materializeBlockLayers — structured data feeds templates', () => {
   afterEach(() => {
     delete (templateRegistry as Record<string, unknown>)['__capture'];
   });
@@ -76,7 +76,7 @@ describe('getLayers — structured data feeds templates', () => {
       templateData: { rows: [['a', 'b']], zoom: 12 },
       templateOverrides: { zoom: '14' },
     };
-    getLayers(block);
+    materializeLayers(block);
     expect(received).not.toBeNull();
     expect(received!['rows']).toEqual([['a', 'b']]);
     // String overrides from {[…]} params win last.
@@ -92,7 +92,7 @@ describe('getLayers — structured data feeds templates', () => {
       '| Alice | 30 |',
     ].join('\n');
     const block = firstBlock(md);
-    const layers = getLayers(block);
+    const layers = materializeLayers(block);
     expect(layers.length).toBeGreaterThan(0);
     const tableLayer = layers.find((l) => l.type === 'table');
     expect(tableLayer).toBeDefined();

package/src/__tests__/imageEditVersions.test.ts

@@ -137,6 +137,8 @@ describe('imageEdit/versions', () => {
     expect(result.version?.path).toMatch(/^\.versions\/state\.\d{8}T\d{6}Z\.json$/);
     // snapshot is inside the sidecar, visible to the parent under the prefix
     expect(await parent.exists(`image_files/${result.version!.path}`)).toBe(true);
+    const gitignore = await parent.readFile('image_files/.gitignore');
+    expect(gitignore && new TextDecoder().decode(gitignore)).toBe('.versions/\n');
   });
 
   it('returns no-state when sidecar is empty', async () => {

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

@@ -1,5 +1,7 @@
 import { describe, it, expect } from 'vitest';
 import {
+  escapePointerSegment,
+  appendPointer,
   toPointer,
   pointerSegments,
   getByPointer,
@@ -7,6 +9,19 @@ import {
   resolveRef,
 } from '../jsonForm/index.js';
 
+describe('pointer composition', () => {
+  it('escapes arbitrary member names and appends them safely', () => {
+    expect(escapePointerSegment('a~/b')).toBe('a~0~1b');
+    expect(appendPointer('/properties', 'a~/b')).toBe('/properties/a~0~1b');
+    expect(appendPointer('', '')).toBe('/');
+    expect(appendPointer('/', 'child')).toBe('//child');
+  });
+
+  it('validates an explicit base pointer before appending', () => {
+    expect(() => appendPointer('/bad~2base', 'child')).toThrow(/Invalid JSON Pointer/);
+  });
+});
+
 describe('toPointer', () => {
   it('keeps pointer-form paths intact', () => {
     expect(toPointer('/a/b')).toBe('/a/b');
@@ -18,13 +33,18 @@ describe('toPointer', () => {
   });
   it('returns empty for root', () => {
     expect(toPointer('')).toBe('');
-    expect(toPointer('/')).toBe('');
+    expect(toPointer('/')).toBe('/');
   });
   it('escapes ~ and / per RFC 6901', () => {
     // dotted form does not allow / inside a segment; we test pointer-form decoding instead.
     expect(pointerSegments('/a~1b')).toEqual(['a/b']);
     expect(pointerSegments('/a~0b')).toEqual(['a~b']);
   });
+  it('rejects malformed pointer syntax and escape sequences', () => {
+    expect(() => pointerSegments('not/a/pointer')).toThrow(/Invalid JSON Pointer/);
+    expect(() => pointerSegments('/bad~2escape')).toThrow(/Invalid JSON Pointer/);
+    expect(() => pointerSegments('/dangling~')).toThrow(/Invalid JSON Pointer/);
+  });
 });
 
 describe('getByPointer', () => {
@@ -43,6 +63,13 @@ describe('getByPointer', () => {
   it('returns the data itself for empty pointer', () => {
     expect(getByPointer(data, '')).toBe(data);
   });
+  it('treats "/" as the empty-string member per RFC 6901', () => {
+    expect(getByPointer({ '': 'empty key' }, '/')).toBe('empty key');
+  });
+  it('requires canonical array indices', () => {
+    expect(getByPointer({ values: ['a'] }, '/values/00')).toBeUndefined();
+    expect(getByPointer({ values: ['a'] }, '/values/-')).toBeUndefined();
+  });
 });
 
 describe('setByPointer', () => {
@@ -75,6 +102,25 @@ describe('setByPointer', () => {
     expect(getByPointer(after, '/a/b/1/c')).toBe(42);
     expect(getByPointer(after, '/a/b/0/c')).toBe(1);
   });
+  it('writes the empty-string member for "/"', () => {
+    expect(setByPointer({}, '/', 'value')).toEqual({ '': 'value' });
+  });
+  it('rejects non-canonical array indices instead of creating NaN properties', () => {
+    expect(() => setByPointer({ items: [] }, '/items/nope', 'x')).toThrow(/array index/i);
+    expect(() => setByPointer({ items: [] }, '/items/01', 'x')).toThrow(/array index/i);
+  });
+  it('writes prototype-shaped keys as safe own data properties', () => {
+    const before = {};
+    const after = setByPointer(before, '/__proto__/polluted', true) as Record<string, unknown>;
+    expect(Object.getPrototypeOf(after)).toBe(Object.prototype);
+    expect(Object.prototype).not.toHaveProperty('polluted');
+    expect(Object.prototype.hasOwnProperty.call(after, '__proto__')).toBe(true);
+    expect(getByPointer(after, '/__proto__/polluted')).toBe(true);
+
+    const constructorPath = setByPointer({}, '/constructor/prototype/polluted', true);
+    expect(getByPointer(constructorPath, '/constructor/prototype/polluted')).toBe(true);
+    expect(Object.prototype).not.toHaveProperty('polluted');
+  });
 });
 
 describe('resolveRef', () => {

package/src/__tests__/layoutBlock.test.ts

@@ -62,8 +62,8 @@ describe('layout container behavior', () => {
     expect(isContainerTemplate('layout')).toBe(true);
   });
 
-  it('renders a layout block through the template registry (getLayers)', async () => {
-    const { getLayers } = await import('../doc/getLayers.js');
+  it('renders a layout block through the template registry', async () => {
+    const { materializeBlockLayers } = await import('../doc/materializeBlockLayers.js');
     const parent: Block = {
       id: 'lay',
       startTime: 0,
@@ -75,7 +75,7 @@ describe('layout container behavior', () => {
         child('box-1', 'rectangle', { x: '760', y: '390', width: '400', height: '300' }),
       ],
     };
-    const layers = getLayers(parent, {});
+    const layers = materializeBlockLayers(parent, { persistentLayers: false }).layers;
     const types = new Set(layers.map((l: Layer) => l.type));
     expect(types.has('text')).toBe(true);
     expect(types.has('shape')).toBe(true);

package/src/__tests__/majorApiTypes.test.ts

@@ -0,0 +1,18 @@
+import { describe, expect, it } from 'vitest';
+import type { PathLayer } from '../schemas/Doc';
+
+describe('major-version core API types', () => {
+  it('requires endpoint markers instead of the removed arrow field', () => {
+    const layer: PathLayer = {
+      id: 'path',
+      type: 'path',
+      position: { x: 0, y: 0, width: 10, height: 10 },
+      content: {
+        d: 'M 0 0 L 10 10',
+        // @ts-expect-error Old documents are read tolerantly, but new code uses endMarker.
+        arrow: 'end',
+      },
+    };
+    expect(layer.content).toHaveProperty('arrow', 'end');
+  });
+});

package/src/__tests__/markdown.test.ts

@@ -831,6 +831,19 @@ describe('parseFrontmatter', () => {
     expect(result).toEqual({ title: 'Hello World', name: 'Jane' });
   });
 
+  it('keeps quoted booleans and numbers as strings and decodes escapes', () => {
+    const result = parseFrontmatter(String.raw`boolean: "true"
+number: "1e3"
+path: "C:\\temp\\\"quoted\""
+single: 'it''s'`);
+    expect(result).toEqual({
+      boolean: 'true',
+      number: '1e3',
+      path: 'C:\\temp\\"quoted"',
+      single: "it's",
+    });
+  });
+
   it('skips comment lines and blank lines', () => {
     const result = parseFrontmatter('# comment\n\ntitle: Test');
     expect(result).toEqual({ title: 'Test' });
@@ -903,6 +916,34 @@ describe('multi-line frontmatter round-trips', () => {
     expect(md).toContain('document-render-as: portrait');
     expect(md).not.toContain('|-');
   });
+
+  it('losslessly round-trips ambiguous and escaped single-line strings', () => {
+    const doc = createDocument();
+    doc.frontmatter = {
+      booleanLike: 'true',
+      numericLike: '1e3',
+      padded: '  keep me  ',
+      quoted: '"literal quotes"',
+      path: 'C:\\temp\\"quoted"',
+    };
+    const md = stringifyMarkdown(doc);
+    expect(md).toContain('booleanLike: "true"');
+    expect(md).toContain('numericLike: "1e3"');
+    expect(parseMarkdown(md).frontmatter).toEqual(doc.frontmatter);
+  });
+
+  it('uses the same escaping rules when updating source frontmatter', () => {
+    const out = setFrontmatterValues('# Body\n', {
+      booleanLike: 'false',
+      padded: ' value ',
+      path: 'C:\\temp\\"quoted"',
+    });
+    expect(parseMarkdown(out).frontmatter).toEqual({
+      booleanLike: 'false',
+      padded: ' value ',
+      path: 'C:\\temp\\"quoted"',
+    });
+  });
 });
 
 describe('frontmatter in parseMarkdown', () => {

package/src/__tests__/matchFontFamily.test.ts

@@ -0,0 +1,114 @@
+import { describe, it, expect } from 'vitest';
+import { matchFontFamily, guessFontFallback } from '../schemas/fontStacks.js';
+import { accentToColorScheme } from '../schemas/themeCompile.js';
+import { deriveScale, isHex } from '../schemas/colorUtils.js';
+
+describe('matchFontFamily', () => {
+  it('matches curated stacks by label', () => {
+    expect(matchFontFamily('Playfair Display')).toEqual({ stackId: 'playfair' });
+    expect(matchFontFamily('JetBrains Mono')).toEqual({ stackId: 'jetbrains-mono' });
+    expect(matchFontFamily('IBM Plex Sans')).toEqual({ stackId: 'ibm-plex-sans' });
+    expect(matchFontFamily('Inter')).toEqual({ stackId: 'inter' });
+  });
+
+  it('matches case-insensitively and ignores surrounding quotes/whitespace', () => {
+    expect(matchFontFamily('  playfair display  ')).toEqual({ stackId: 'playfair' });
+    expect(matchFontFamily('"Merriweather"')).toEqual({ stackId: 'merriweather' });
+    expect(matchFontFamily("'LORA'")).toEqual({ stackId: 'lora' });
+  });
+
+  it('matches explicit aliases and Google family names', () => {
+    expect(matchFontFamily('Playfair')).toEqual({ stackId: 'playfair' });
+    expect(matchFontFamily('Source Serif Pro')).toEqual({ stackId: 'source-serif' });
+    expect(matchFontFamily('Source Serif 4')).toEqual({ stackId: 'source-serif' });
+    expect(matchFontFamily('Crimson Pro')).toEqual({ stackId: 'crimson' });
+    expect(matchFontFamily('Cormorant')).toEqual({ stackId: 'cormorant' });
+  });
+
+  it('maps web-safe faces onto the system stacks that already anchor them', () => {
+    expect(matchFontFamily('Georgia')).toEqual({ stackId: 'system-serif' });
+    expect(matchFontFamily('Times New Roman')).toEqual({ stackId: 'system-serif' });
+    expect(matchFontFamily('Consolas')).toEqual({ stackId: 'system-mono' });
+    expect(matchFontFamily('Courier New')).toEqual({ stackId: 'system-mono' });
+    expect(matchFontFamily('Segoe UI')).toEqual({ stackId: 'system-sans' });
+  });
+
+  it('preserves unknown faces as custom fonts with a heuristic fallback', () => {
+    expect(matchFontFamily('Calibri')).toEqual({
+      custom: { name: 'Calibri', fallback: 'sans-serif' },
+    });
+    expect(matchFontFamily('Calibri Light')).toEqual({
+      custom: { name: 'Calibri Light', fallback: 'sans-serif' },
+    });
+    expect(matchFontFamily('Cambria')).toEqual({
+      custom: { name: 'Cambria', fallback: 'serif' },
+    });
+    expect(matchFontFamily('Aptos')).toEqual({
+      custom: { name: 'Aptos', fallback: 'sans-serif' },
+    });
+  });
+
+  it('keeps original casing but strips quotes on custom names', () => {
+    expect(matchFontFamily('"Neue Haas Grotesk"')).toEqual({
+      custom: { name: 'Neue Haas Grotesk', fallback: 'sans-serif' },
+    });
+  });
+
+  it('resolves empty/blank names to system-sans', () => {
+    expect(matchFontFamily('')).toEqual({ stackId: 'system-sans' });
+    expect(matchFontFamily('   ')).toEqual({ stackId: 'system-sans' });
+  });
+});
+
+describe('guessFontFallback', () => {
+  it('detects monospace faces', () => {
+    expect(guessFontFallback('Cascadia Code')).toBe('monospace');
+    expect(guessFontFallback('Roboto Mono')).toBe('monospace');
+    expect(guessFontFallback('Courier Prime')).toBe('monospace');
+  });
+
+  it('detects serif faces by keyword and by known serif names', () => {
+    expect(guessFontFallback('Adobe Caslon Pro')).toBe('serif');
+    expect(guessFontFallback('Bodoni Moda')).toBe('serif');
+    expect(guessFontFallback('Palatino Linotype')).toBe('serif');
+    expect(guessFontFallback('Awesome Serif')).toBe('serif');
+  });
+
+  it('does not treat sans-serif names as serif', () => {
+    expect(guessFontFallback('PT Sans Serif Whatever')).toBe('sans-serif');
+    expect(guessFontFallback('Open Sans')).toBe('sans-serif');
+  });
+
+  it('defaults to sans-serif and never guesses system-ui', () => {
+    expect(guessFontFallback('Neue Haas Grotesk')).toBe('sans-serif');
+    expect(guessFontFallback('Futura')).toBe('sans-serif');
+  });
+});
+
+describe('accentToColorScheme', () => {
+  it('derives the same scheme the editor previously derived inline', () => {
+    // Parity with the original editor-react schemeFromAccent implementation.
+    const accent = '#63b3ed';
+    const scale = deriveScale(accent, 0.3);
+    expect(accentToColorScheme(accent)).toEqual({
+      bg: scale.darker2,
+      text: scale.lighter2,
+      accent: scale.base,
+    });
+  });
+
+  it('returns valid hex colors for every slot', () => {
+    const scheme = accentToColorScheme('#c05621');
+    expect(isHex(scheme.bg)).toBe(true);
+    expect(isHex(scheme.text)).toBe(true);
+    expect(isHex(scheme.accent)).toBe(true);
+  });
+
+  it('falls back to a neutral scheme on invalid input', () => {
+    expect(accentToColorScheme('not-a-color')).toEqual({
+      bg: '#1a202c',
+      text: '#e2e8f0',
+      accent: '#63b3ed',
+    });
+  });
+});

package/src/__tests__/materializeBlockLayers.test.ts

@@ -0,0 +1,135 @@
+import { describe, expect, it, vi } from 'vitest';
+import { DEFAULT_THEME, expandDocBlocks } from '../doc/templates/index.js';
+import { materializeBlockLayers } from '../doc/materializeBlockLayers.js';
+import type { CustomTemplateDefinition } from '../schemas/CustomTemplates.js';
+import type { Block, Layer, TextLayer } from '../schemas/Doc.js';
+import type { TemplateBlock } from '../schemas/BlockTemplates.js';
+
+const titleBlock: TemplateBlock = {
+  template: 'title',
+  id: 'title-1',
+  duration: 5,
+  audioSegment: 0,
+  title: 'A canonical materializer',
+};
+
+describe('materializeBlockLayers', () => {
+  it('returns owned layers and metadata for built-in and authored blocks', () => {
+    const templated = materializeBlockLayers(titleBlock, { persistentLayers: false });
+    expect(templated.source).toBe('template');
+    expect(templated.diagnostic).toBeUndefined();
+    expect(templated.layers.length).toBeGreaterThan(0);
+
+    const authoredLayer: Layer = {
+      id: 'authored',
+      type: 'shape',
+      content: { shape: 'rect', fill: '#123456' },
+      position: { x: 0, y: 0, width: 10, height: 10 },
+    };
+    const authored: Block = {
+      id: 'raw',
+      startTime: 0,
+      duration: 5,
+      audioSegment: 0,
+      layers: [authoredLayer],
+    };
+    const materialized = materializeBlockLayers(authored, { persistentLayers: false });
+    expect(materialized.source).toBe('authored');
+    expect(materialized.layers).toEqual([authoredLayer]);
+    expect(materialized.layers[0]).not.toBe(authoredLayer);
+  });
+
+  it('resolves document-scoped custom templates in the on-demand API', () => {
+    const customTemplate: CustomTemplateDefinition = {
+      name: 'hero',
+      label: 'Hero',
+      viewport: { width: 1920, height: 1080 },
+      layers: [
+        {
+          id: 'hero-title',
+          type: 'text',
+          position: { x: '5%', y: '10%', width: '90%' },
+          content: { text: '{title}', style: { fontSize: 64, color: '#000000' } },
+        },
+      ],
+    };
+    const block = {
+      ...titleBlock,
+      template: 'hero',
+      title: 'Doc-scoped',
+    } as unknown as TemplateBlock;
+
+    const result = materializeBlockLayers(block, {
+      customTemplates: [customTemplate],
+      persistentLayers: false,
+    });
+
+    expect(result.source).toBe('template');
+    expect((result.layers[0] as TextLayer).content.text).toBe('Doc-scoped');
+  });
+
+  it('returns structured diagnostics and a visible fallback without logging', () => {
+    const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
+    const error = vi.spyOn(console, 'error').mockImplementation(() => {});
+    const unknown = { ...titleBlock, template: 'not-registered' } as unknown as TemplateBlock;
+
+    const result = materializeBlockLayers(unknown, { persistentLayers: false });
+
+    expect(result.source).toBe('fallback');
+    expect(result.diagnostic).toEqual({
+      code: 'unknown-template',
+      template: 'not-registered',
+      message: 'Unknown template "not-registered"',
+    });
+    expect(result.layers.some((layer) => layer.id === 'fallback-notice')).toBe(true);
+    expect(warn).not.toHaveBeenCalled();
+    expect(error).not.toHaveBeenCalled();
+    warn.mockRestore();
+    error.mockRestore();
+  });
+
+  it('supports an explicit empty failure policy', () => {
+    const unknown = { ...titleBlock, template: 'not-registered' } as unknown as TemplateBlock;
+    const result = materializeBlockLayers(unknown, {
+      failureMode: 'empty',
+      persistentLayers: false,
+    });
+
+    expect(result.source).toBe('empty');
+    expect(result.layers).toEqual([]);
+    expect(result.diagnostic?.code).toBe('unknown-template');
+  });
+
+  it('inherits theme persistent layers by default and has an explicit opt-out', () => {
+    const theme = {
+      ...DEFAULT_THEME,
+      persistentLayers: {
+        bottomLayers: [
+          {
+            template: 'solidBackground' as const,
+            config: { type: 'solidBackground' as const, color: '#123456' },
+          },
+        ],
+      },
+    };
+
+    const inherited = materializeBlockLayers(titleBlock, { theme });
+    const disabled = materializeBlockLayers(titleBlock, { theme, persistentLayers: false });
+
+    expect(inherited.layers[0]?.id).toContain('solid');
+    expect(disabled.layers[0]?.id).not.toContain('solid');
+  });
+
+  it('is the only materialization path used by timed expansion', () => {
+    const diagnostics: string[] = [];
+    const unknown = { ...titleBlock, template: 'not-registered' } as unknown as TemplateBlock;
+    const direct = materializeBlockLayers(unknown, { persistentLayers: false });
+    const [scheduled] = expandDocBlocks([unknown], {
+      persistentLayers: false,
+      onDiagnostic: (diagnostic) => diagnostics.push(diagnostic.code),
+    });
+
+    expect(scheduled.layers).toEqual(direct.layers);
+    expect(diagnostics).toEqual(['unknown-template']);
+  });
+});

package/src/__tests__/materializeTestUtils.ts

@@ -0,0 +1,17 @@
+import type { Layer } from '../schemas/Doc.js';
+import type { DocBlock } from '../schemas/BlockTemplates.js';
+import {
+  materializeBlockLayers,
+  type MaterializeBlockLayersOptions,
+} from '../doc/materializeBlockLayers.js';
+
+/** Materialize isolated test fixtures without inheriting theme atmosphere. */
+export function materializeLayers(
+  block: DocBlock,
+  options: MaterializeBlockLayersOptions = {},
+): Layer[] {
+  return materializeBlockLayers(block, {
+    persistentLayers: false,
+    ...options,
+  }).layers;
+}